SoundCloud for Developers

Discover, connect and build

We use cookies for various purposes including analytics and personalized marketing. By continuing to use the service, you agree to our use of cookies as described in the Cookie Policy.

HTTP API Reference

The SoundCloud API exposes SoundCloud resources like sounds, sets and users. These resources can be accessed and manipulated using the HTTP methods GET, POST, PUT and DELETE.

All SoundCloud resources are accessed and manipulated in a similar way. A list of the latest resource is usually available through /[resource name], a single specific resource through /[resource name][id] and related subresources like a tracks comments through /[resource name]/[id]/[subresource name].

Unless otherwise specified, the base URL for API endpoints is:

https://api.soundcloud.com

To access public resources you just have to pass a client_id parameter:

$ curl https://api.soundcloud.com/tracks?client_id=YOUR_CLIENT_ID

To act on behalf of a SoundCloud user, they must first authenticate your app.

/connect

Full URI: https://soundcloud.com/connect

The OAuth2 authorization endpoint. Your app redirects a user to this endpoint, allowing them to delegate access to their account.

Parameters

Parameter Type Description
client_id string The client id belonging to your application
redirect_uri string The redirect uri you have configured for your application
response_type enumeration (code, token, code_and_token)
scope string '*'
display string Can specify a value of 'popup' for mobile optimized screen
state string Any value included here will be appended to the redirect URI

/oauth2/token

The OAuth2 token endpoint. This endpoint accepts POST requests and is used to provision access tokens once a user has authorized your application.

Note All parameters must be sent in the request body, not as part of the query string.

Parameters

Parameter Type Description
client_id string The client id belonging to your application
client_secret string The client secret belonging to your application
redirect_uri string The redirect uri you have configured for your application
grant_type enumeration (authorization_code, refresh_token, password, client_credentials)
code string The authorization code obtained when user is sent to redirect_uri

Example

$ curl -X POST "https://api.soundcloud.com/oauth2/token" \\           -F 'client_id=YOUR_CLIENT_ID' \\           -F 'client_secret=YOUR_CLIENT_SECRET' \\           -F 'grant_type=authorization_code' \\           -F 'redirect_uri=https://yourapp.com/soundcloud/oauth-callback' \\           -F 'code=0000000EYAA1CRGodSoKJ9WsdhqVQr3g'
{
  "access_token": "04u7h-4cc355-70k3n",
  "scope": "*"
}

/users

A SoundCloud user

Example

$ curl "https://api.soundcloud.com/users/3207?client_id=YOUR_CLIENT_ID"
{
  "id": 3207,
  "permalink": "jwagener",
  "username": "Johannes Wagener",
  "uri": "https://api.soundcloud.com/users/3207",
  "permalink_url": "https://soundcloud.com/jwagener",
  "avatar_url": "https://i1.sndcdn.com/avatars-000001552142-pbw8yd-large.jpg?142a848",
  "country": "Germany",
  "full_name": "Johannes Wagener",
  "city": "Berlin",
  "description": "<b>Hacker at SoundCloud</b>\r\n\r\nSome of my recent Hacks:\r\n\r\nsoundiverse.com \r\nbrowse recordings with the FiRe app by artwork\r\n\r\ntopbillin.com \r\nfind people to follow on SoundCloud\r\n\r\nchatter.fm \r\nget your account hooked up with a voicebox\r\n\r\nrecbutton.com \r\nrecord straight to your soundcloud account",
  "discogs_name": null,
  "myspace_name": null,
  "website": "http://johannes.wagener.cc",
  "website_title": "johannes.wagener.cc",
  "online": true,
  "track_count": 12,
  "playlist_count": 1,
  "followers_count": 417,
  "followings_count": 174,
  "public_favorites_count": 26
}

Properties

name description example value
id RO integer ID 123
permalink RW permalink of the resource "sbahn-sounds"
username RW username "Doctor Wilson"
uri RO API resource URL https://api.soundcloud.com/users/3207
permalink_url RO URL to the SoundCloud.com page "https://soundcloud.com/bryan/sbahn-sounds"
avatar_url RO URL to a JPEG image "https://i1.sndcdn.com/avatars-000011353294-n0axp1-large.jpg"
country RO country "Germany"
full_name RO first and last name "Tom Wilson"
city RO city "Berlin"
description RW description "Buskers playing in the S-Bahn station in Berlin"
discogs-name RO Discogs name "myrandomband"
myspace-name RO MySpace name "myrandomband"
website RW a URL to the website "http://facebook.com/myrandomband"
website-title RW a custom title for the website "myrandomband on Facebook"
online RO online status (boolean) true
track_count RO number of public tracks 4
playlist_count RO number of public playlists 5
followers_count RO number of followers 54
followings_count RO number of followed users 75
public_favorites_count RO number of favorited public tracks 7
avatar_data WO binary data of user avatar (only for uploading)

Subresources

Methods Path Description
GET /users/{id} a user
GET /users/{id}/tracks list of tracks of the user
GET /users/{id}/playlists list of playlists (sets) of the user
GET /users/{id}/followings list of users who are followed by the user
GET, PUT, DELETE /users/{id}/followings/{id} a user who is followed by the user
GET /users/{id}/followers list of users who are following the user
GET /users/{id}/followers/{id} user who is following the user
GET /users/{id}/comments list of comments from this user
GET /users/{id}/favorites list of tracks favorited by the user
GET /users/{id}/web-profiles list of web profiles

Filters

Parameter Type Description
q string a string to search for (see search documentation)

/tracks

A SoundCloud Track

Example

$ curl "https://api.soundcloud.com/tracks/13158665?client_id=YOUR_CLIENT_ID"
{
  "id": 13158665,
  "created_at": "2011/04/06 15:37:43 +0000",
  "user_id": 3699101,
  "duration": 18109,
  "commentable": true,
  "state": "finished",
  "sharing": "public",
  "tag_list": "soundcloud:source=iphone-record",
  "permalink": "munching-at-tiannas-house",
  "description": null,
  "streamable": true,
  "downloadable": true,
  "genre": null,
  "release": null,
  "purchase_url": null,
  "label_id": null,
  "label_name": null,
  "isrc": null,
  "video_url": null,
  "track_type": "recording",
  "key_signature": null,
  "bpm": null,
  "title": "Munching at Tiannas house",
  "release_year": null,
  "release_month": null,
  "release_day": null,
  "original_format": "m4a",
  "original_content_size": 10211857,
  "license": "all-rights-reserved",
  "uri": "https://api.soundcloud.com/tracks/13158665",
  "permalink_url": "https://soundcloud.com/user2835985/munching-at-tiannas-house",
  "artwork_url": null,
  "waveform_url": "https://w1.sndcdn.com/fxguEjG4ax6B_m.png",
  "user": {
    "id": 3699101,
    "permalink": "user2835985",
    "username": "user2835985",
    "uri": "https://api.soundcloud.com/users/3699101",
    "permalink_url": "https://soundcloud.com/user2835985",
    "avatar_url": "https://a1.sndcdn.com/images/default_avatar_large.png?142a848"
  },
  "stream_url": "https://api.soundcloud.com/tracks/13158665/stream",
  "download_url": "https://api.soundcloud.com/tracks/13158665/download",
  "playback_count": 0,
  "download_count": 0,
  "favoritings_count": 0,
  "comment_count": 0,
  "attachments_uri": "https://api.soundcloud.com/tracks/13158665/attachments"
}

Properties

name description example value
id RO integer ID 123
created_at RO timestamp of creation "2009/08/13 18:30:10 +0000"
user_id RO user-id of the owner 343
user RO mini user representation of the owner {id: 343, username: "Doctor Wilson"...}
title RW track title "S-Bahn Sounds"
permalink RW permalink of the resource "sbahn-sounds"
permalink_url RO URL to the SoundCloud.com page "https://soundcloud.com/bryan/sbahn-sounds"
uri RO API resource URL "https://api.soundcloud.com/tracks/123"
sharing RW public/private sharing "public"
embeddable_by RW who can embed this track or playlist "all", "me", or "none"
purchase_url RW external purchase link "http://amazon.com/buy/a43aj0b03"
artwork_url RO URL to a JPEG image "https://i1.sndcdn.com/a....-large.jpg?142a848"

JPEG, PNG and GIF are accepted when uploading and will be encoded to multiple JPEGs in these formats:

  • t500x500: 500×500
  • crop: 400×400
  • t300x300: 300×300
  • large: 100×100 (default)
  • t67x67: 67×67 (only on artworks)
  • badge: 47×47
  • small: 32×32
  • tiny: 20×20 (on artworks)
  • tiny: 18×18 (on avatars)
  • mini: 16×16

The URL is pointing to the format large by default. If you want to use a different format you have to replace large with the specific format name in the image URL:

For example:

https://i1.sndcdn.com/avatars-000000011308-xq0whu-large.jpg?b17c165

to

https://i1.sndcdn.com/avatars-000000011308-xq0whu-crop.jpg?b17c165

description RW HTML description "my first track"
label RO label mini user object {id:123, username: "BeatLabel"...}
duration RO duration in milliseconds 1203400
genre RW genre "HipHop"
tag_list RW list of tags "tag1 \"hip hop\" geo:lat=32.444 geo:lon=55.33"

The tag_list property contains a list of tags separated by spaces. Multiword tags are quoted in doublequotes. We also support machine tags that follow the pattern NAMESPACE:KEY=VALUE. For example:

  • geo:lat=43.555
  • camel:size=medium
  • “machine:tag=with space”

Machine tags are not revealed to the user on the track pages.

label_id RO id of the label user 54677
label_name RW label name "BeatLabel"
release RW release number 3234
release_day RO day of the release 21
release_month RO month of the release 5
release_year RO year of the release 2001
release_date WO string, formatted as yyyy-mm-dd, representing release date 2001-05-21
streamable RW streamable via API (boolean) true
downloadable RW downloadable (boolean) true
state RO encoding state "finished"

Possible values: * “processing” * “failed” * “finished”

license RW creative common license "no-rights-reserved"

Possible values: * “no-rights-reserved” * “all-rights-reserved” * “cc-by” * “cc-by-nc” * “cc-by-nd” * “cc-by-sa” * “cc-by-nc-nd” * “cc-by-nc-sa”

track_type RO track type "recording"

Possible values: * “original” * “remix” * “live” * “recording” * “spoken” * “podcast” * “demo” * “in progress” * “stem” * “loop” * “sound effect” * “sample” * “other”

waveform_url RO URL to PNG waveform image "https://w1.sndcdn.com/fxguEjG4ax6B_m.png"
download_url RO URL to original file "https://api.soundcloud.com/tracks/3/download"
stream_url RO link to 128kbs mp3 stream "https://api.soundcloud.com/tracks/3/stream"
video_url RO a link to a video page "http://vimeo.com/3302330"
bpm RO beats per minute 120
commentable RW track commentable (boolean) true
isrc RW track ISRC "I123-545454"
key_signature RO track key "Cmaj"
comment_count RO track comment count 12
download_count RO track download count 45
playback_count RO track play count 435
favoritings_count RO track favoriting count 6
original_format RO file format of the original file "aiff"
original_content_size RO size in bytes of the original file 10211857
asset_data WO binary data of the audio file (only for uploading)
artwork_data WO binary data of the artwork image (only for uploading, for PRO users)
user_favorite RO track favorite of current user (boolean, authenticated requests only) 1

Subresources

Methods Path Description
GET, PUT, DELETE /tracks/{id} a track
GET /tracks/{id}/comments comments for the track
DELETE /tracks/{id}/comments/{comment-id} a comment for the track
GET /tracks/{id}/favoriters users who favorited the track
GET /tracks/{id}/favoriters/{user-id} a user who has favorited to the track
GET /tracks/{id}/related get all related tracks for input track id

Filters

Parameter Type Description
q string a string to search for (see search documentation)
tags list a comma separated list of tags
filter enumeration (all,public,private)
license enumeration Filter on license. (see license attribute)
bpm[from] number return tracks with at least this bpm value
bpm[to] number return tracks with at most this bpm value
duration[from] number return tracks with at least this duration (in millis)
duration[to] number return tracks with at most this duration (in millis)
created_at[from] date (yyyy-mm-dd hh:mm:ss) return tracks created at this date or later
created_at[to] date (yyyy-mm-dd hh:mm:ss) return tracks created at this date or earlier
ids list a comma separated list of track ids to filter on
genres list a comma separated list of genres
types enumeration a comma separated list of types

/playlists

A SoundCloud Set is internally called playlists due to some naming restrictions.

Example

$ curl "https://api.soundcloud.com/playlists/405726?client_id=YOUR_CLIENT_ID"
{
  "kind": "playlist",
  "id": 405726,
  "created_at": "2010/11/02 09:24:50 +0000",
  "user_id": 3207,
  "duration": 154516,
  "sharing": "public",
  "tag_list": "",
  "permalink": "field-recordings",
  "track_count": 5,
  "streamable": true,
  "downloadable": true,
  "embeddable_by": "me",
  "purchase_url": null,
  "label_id": null,
  "type": "other",
  "playlist_type": "other",
  "ean": "",
  "description": "a couple of field recordings to test http://soundiverse.com.\r\n\r\nrecorded with the fire recorder: https://soundcloud.com/apps/fire",
  "genre": "",
  "release": "",
  "purchase_title": null,
  "label_name": "",
  "title": "Field Recordings",
  "release_year": null,
  "release_month": null,
  "release_day": null,
  "license": "all-rights-reserved",
  "uri": "https://api.soundcloud.com/playlists/405726",
  "permalink_url": "https://soundcloud.com/jwagener/sets/field-recordings",
  "artwork_url": "https://i1.sndcdn.com/artworks-000025801802-1msl1i-large.jpg?5e64f12",
  "user": {
    "id": 3207,
    "kind": "user",
    "permalink": "jwagener",
    "username": "Johannes Wagener",
    "uri": "https://api.soundcloud.com/users/3207",
    "permalink_url": "https://soundcloud.com/jwagener",
    "avatar_url": "https://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
  },
  "tracks": [
    {
      "kind": "track",
      "id": 6621631,
      "created_at": "2010/11/02 09:08:43 +0000",
      "user_id": 3207,
      "duration": 27099,
      "commentable": true,
      "state": "finished",
      "original_content_size": 2382624,
      "sharing": "public",
      "tag_list": "Fieldrecording geo:lat=52.527544 geo:lon=13.402905",
      "permalink": "coffee-machine",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": false,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": "",
      "title": "coffee machine",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "https://api.soundcloud.com/tracks/6621631",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "https://api.soundcloud.com/users/3207",
        "permalink_url": "https://soundcloud.com/jwagener",
        "avatar_url": "https://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "permalink_url": "https://soundcloud.com/jwagener/coffee-machine",
      "artwork_url": "https://i1.sndcdn.com/artworks-000002863219-4zpxc0-large.jpg?5e64f12",
      "waveform_url": "https://w1.sndcdn.com/Yva1Qimi7TVd_m.png",
      "stream_url": "https://api.soundcloud.com/tracks/6621631/stream",
      "playback_count": 1249,
      "download_count": 114,
      "favoritings_count": 14,
      "comment_count": 11,
      "attachments_uri": "https://api.soundcloud.com/tracks/6621631/attachments"
    },
    {
      "kind": "track",
      "id": 6621549,
      "created_at": "2010/11/02 09:00:23 +0000",
      "user_id": 3207,
      "duration": 65618,
      "commentable": true,
      "state": "finished",
      "original_content_size": 5780256,
      "sharing": "public",
      "tag_list": "Fieldrecording geo:lat=52.528181 geo:lon=13.412658",
      "permalink": "tram-in-berlin",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": true,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": "",
      "title": "tram in berlin",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "recording",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "https://api.soundcloud.com/tracks/6621549",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "https://api.soundcloud.com/users/3207",
        "permalink_url": "https://soundcloud.com/jwagener",
        "avatar_url": "https://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "permalink_url": "https://soundcloud.com/jwagener/tram-in-berlin",
      "artwork_url": "https://i1.sndcdn.com/artworks-000002863163-6f2aqe-large.jpg?5e64f12",
      "waveform_url": "https://w1.sndcdn.com/u04ibjx6FYdM_m.png",
      "stream_url": "https://api.soundcloud.com/tracks/6621549/stream",
      "download_url": "https://api.soundcloud.com/tracks/6621549/download",
      "playback_count": 578,
      "download_count": 93,
      "favoritings_count": 4,
      "comment_count": 3,
      "attachments_uri": "https://api.soundcloud.com/tracks/6621549/attachments"
    },
    {
      "kind": "track",
      "id": 6668072,
      "created_at": "2010/11/03 19:47:11 +0000",
      "user_id": 3207,
      "duration": 21871,
      "commentable": true,
      "state": "finished",
      "original_content_size": 1921800,
      "sharing": "public",
      "tag_list": "geo:lat=52.527529 geo:lon=13.402961",
      "permalink": "alex-playing-drums",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": true,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": null,
      "title": "alex playing drums",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "recording",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "https://api.soundcloud.com/tracks/6668072",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "https://api.soundcloud.com/users/3207",
        "permalink_url": "https://soundcloud.com/jwagener",
        "avatar_url": "https://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "permalink_url": "https://soundcloud.com/jwagener/alex-playing-drums",
      "artwork_url": "https://i1.sndcdn.com/artworks-000002888918-takbu6-large.jpg?5e64f12",
      "waveform_url": "https://w1.sndcdn.com/MQnxWxIH94ai_m.png",
      "stream_url": "https://api.soundcloud.com/tracks/6668072/stream",
      "download_url": "https://api.soundcloud.com/tracks/6668072/download",
      "playback_count": 400,
      "download_count": 84,
      "favoritings_count": 2,
      "comment_count": 1,
      "attachments_uri": "https://api.soundcloud.com/tracks/6668072/attachments"
    },
    {
      "kind": "track",
      "id": 6698933,
      "created_at": "2010/11/04 19:09:32 +0000",
      "user_id": 3207,
      "duration": 12726,
      "commentable": true,
      "state": "finished",
      "original_content_size": 1116936,
      "sharing": "public",
      "tag_list": "geo:lat=52.528450 geo:lon=13.404099",
      "permalink": "typing",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": false,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": null,
      "title": "typing",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "recording",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "https://api.soundcloud.com/tracks/6698933",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "https://api.soundcloud.com/users/3207",
        "permalink_url": "https://soundcloud.com/jwagener",
        "avatar_url": "https://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "permalink_url": "https://soundcloud.com/jwagener/typing",
      "artwork_url": "https://i1.sndcdn.com/artworks-000002903990-le6t7d-large.jpg?5e64f12",
      "waveform_url": "https://w1.sndcdn.com/ZSil4IqhP6Hh_m.png",
      "stream_url": "https://api.soundcloud.com/tracks/6698933/stream",
      "playback_count": 1151,
      "download_count": 102,
      "favoritings_count": 1,
      "comment_count": 0,
      "attachments_uri": "https://api.soundcloud.com/tracks/6698933/attachments"
    },
    {
      "kind": "track",
      "id": 6770077,
      "created_at": "2010/11/07 02:45:11 +0000",
      "user_id": 3207,
      "duration": 27202,
      "commentable": true,
      "state": "finished",
      "original_content_size": 2392840,
      "sharing": "public",
      "tag_list": "geo:lat=52.531203 geo:lon=13.412165",
      "permalink": "bassy",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": true,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": "",
      "title": "bassy",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "recording",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "https://api.soundcloud.com/tracks/6770077",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "https://api.soundcloud.com/users/3207",
        "permalink_url": "https://soundcloud.com/jwagener",
        "avatar_url": "https://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "permalink_url": "https://soundcloud.com/jwagener/bassy",
      "artwork_url": "https://i1.sndcdn.com/artworks-000002938592-960ejc-large.jpg?5e64f12",
      "waveform_url": "https://w1.sndcdn.com/bxaiyNJt3vWK_m.png",
      "stream_url": "https://api.soundcloud.com/tracks/6770077/stream",
      "download_url": "https://api.soundcloud.com/tracks/6770077/download",
      "playback_count": 335,
      "download_count": 78,
      "favoritings_count": 1,
      "comment_count": 1,
      "attachments_uri": "https://api.soundcloud.com/tracks/6770077/attachments"
    }
  ]
}

Properties

name description example value
id RO integer ID 123
created_at RO timestamp of creation "2009/08/13 18:30:10 +0000"
user_id RO user-id of the owner 343
user RO mini user representation of the owner {id: 343, username: "Doctor Wilson"...}
title RW track title "S-Bahn Sounds"
permalink RW permalink of the resource "sbahn-sounds"
permalink_url RO URL to the SoundCloud.com page "https://soundcloud.com/bryan/sbahn-sounds"
uri RO API resource URL "https://api.soundcloud.com/tracks/123"
sharing RW public/private sharing "public"
embeddable_by RW who can embed this track or playlist "all", "me", or "none"
purchase_url RW external purchase link "http://amazon.com/buy/a43aj0b03"
artwork_url RO URL to a JPEG image "https://i1.sndcdn.com/a....-large.jpg?142a848"

JPEG, PNG and GIF are accepted when uploading and will be encoded to multiple JPEGs in these formats:

  • t500x500: 500×500
  • crop: 400×400
  • t300x300: 300×300
  • large: 100×100 (default)
  • t67x67: 67×67 (only on artworks)
  • badge: 47×47
  • small: 32×32
  • tiny: 20×20 (on artworks)
  • tiny: 18×18 (on avatars)
  • mini: 16×16

The URL is pointing to the format large by default. If you want to use a different format you have to replace large with the specific format name in the image URL:

For example:

https://i1.sndcdn.com/avatars-000000011308-xq0whu-large.jpg?b17c165

to

https://i1.sndcdn.com/avatars-000000011308-xq0whu-crop.jpg?b17c165

description RW HTML description "my first track"
label RO label mini user object {id:123, username: "BeatLabel"...}
duration RO duration in milliseconds 1203400
genre RW genre "HipHop"
tag_list RW list of tags "tag1 \"hip hop\" geo:lat=32.444 geo:lon=55.33"

The tag_list property contains a list of tags separated by spaces. Multiword tags are quoted in doublequotes. We also support machine tags that follow the pattern NAMESPACE:KEY=VALUE. For example:

  • geo:lat=43.555
  • camel:size=medium
  • “machine:tag=with space”

Machine tags are not revealed to the user on the track pages.

label_id RO id of the label user 54677
label_name RW label name "BeatLabel"
release RW release number 3234
release_day RO day of the release 21
release_month RO month of the release 5
release_year RO year of the release 2001
release_date WO string, formatted as yyyy-mm-dd, representing release date 2001-05-21
streamable RO streamable via API (boolean) true

This will aggregate the playlists tracks streamable attribute. Its value will be nil if not all tracks have the same streamable value.

downloadable RO downloadable (boolean) true

This will aggregate the playlists tracks downloadable attribute. Its value will be nil if not all tracks have the same downloadable value.

ean RW EAN identifier for the playlist "123-4354345-43"
playlist_type RW playlist type "recording"

Possible values: * “ep single” * “album” * “compilation” * “project files” * “archive” * “showcase” * “demo” * “sample pack” * “other”

Filters

Parameter Type Description
representation string compact (no track listing) or id (track listing only contains track IDs).
q string a string to search for (see search documentation). When this parameter is used, only compact representations are returned.

/me

The /me resource allows you to get information about the authenticated user and easily access their related subresources like tracks, followings, followers and so on.

Example

$ curl "https://api.soundcloud.com/me"
{
  "id": 3207,
  "permalink": "jwagener",
  "username": "Johannes Wagener",
  "uri": "https://api.soundcloud.com/users/3207",
  "permalink_url": "https://soundcloud.com/jwagener",
  "avatar_url": "https://i1.sndcdn.com/avatars-000001552142-pbw8yd-large.jpg?142a848",
  "country": "Germany",
  "full_name": "Johannes Wagener",
  "city": "Berlin",
  "description": "<b>Hacker at SoundCloud</b>\r\n\r\nSome of my recent Hacks:\r\n\r\nsoundiverse.com \r\nbrowse recordings with the FiRe app by artwork\r\n\r\ntopbillin.com \r\nfind people to follow on SoundCloud\r\n\r\nchatter.fm \r\nget your account hooked up with a voicebox\r\n\r\nrecbutton.com \r\nrecord straight to your soundcloud account",
  "discogs_name": null,
  "myspace_name": null,
  "website": "http://johannes.wagener.cc",
  "website_title": "johannes.wagener.cc",
  "online": true,
  "track_count": 12,
  "playlist_count": 1,
  "followers_count": 416,
  "followings_count": 174,
  "public_favorites_count": 26,
  "plan": "Pro Plus",
  "private_tracks_count": 63,
  "private_playlists_count": 3,
  "primary_email_confirmed": true
}

Properties

name description example value
id RO integer ID 123
permalink RW permalink of the resource "sbahn-sounds"
username RW username "Doctor Wilson"
uri RO API resource URL https://api.soundcloud.com/users/3207
permalink_url RO URL to the SoundCloud.com page "https://soundcloud.com/bryan/sbahn-sounds"
avatar_url RO URL to a JPEG image "https://i1.sndcdn.com/avatars-000011353294-n0axp1-large.jpg"
country RO country "Germany"
full_name RO first and last name "Tom Wilson"
city RO city "Berlin"
description RW description "Buskers playing in the S-Bahn station in Berlin"
discogs-name RO Discogs name "myrandomband"
myspace-name RO MySpace name "myrandomband"
website RW a URL to the website "http://facebook.com/myrandomband"
website-title RW a custom title for the website "myrandomband on Facebook"
online RO online status (boolean) true
track_count RO number of public tracks 4
playlist_count RO number of public playlists 5
followers_count RO number of followers 54
followings_count RO number of followed users 75
public_favorites_count RO number of favorited public tracks 7
avatar_data WO binary data of user avatar (only for uploading)
plan RO subscription plan of the user Pro Plus
private_tracks_count RO number of private tracks 34
private_playlists_count RO number of private playlists 6
primary_email_confirmed RO boolean if email is confirmed true

Subresources

All subresources that are documented in /users are also available via /me. For example /me/tracks will return the tracks owned by the user. Additionally you can access the users dashboard activities through /me/activities and their connected external accounts through /me/connections.

Methods Path Description
GET /users/{id} a user
GET /users/{id}/tracks list of tracks of the user
GET /users/{id}/playlists list of playlists (sets) of the user
GET /users/{id}/followings list of users who are followed by the user
GET, PUT, DELETE /users/{id}/followings/{id} a user who is followed by the user
GET /users/{id}/followers list of users who are following the user
GET /users/{id}/followers/{id} user who is following the user
GET /users/{id}/comments list of comments from this user
GET /users/{id}/favorites list of tracks favorited by the user
GET /users/{id}/web-profiles list of web profiles

/me/connections

Connections represent the external profiles (like twitter, tumblr or facebook profiles and pages) that are connected to a SoundCloud user. The connection ids can be used to share tracks and playlists to social network. This is described for tracks and playlists here.

Example

Method Resource
GET /me/connections
GET /me/connections/{connection_id}

GET /me/connections

Type: Collection of connections

Retrieves connections for the authenticated user.

$ curl "https://api.soundcloud.com/me/connections"
[
  {
    "created_at": "2010/12/05 16:46:34 +0000",
    "display_name": "a facebook artist page",
    "id": 313104,
    "post_favorite": false,
    "post_publish": false,
    "service": "facebook_page",
    "type": "facebook_page",
    "uri": "https://api.soundcloud.com/connections/313104"
  },
  {
    "created_at": "2010/12/04 02:28:32 +0000",
    "display_name": "mytwittername",
    "id": 310235,
    "post_favorite": false,
    "post_publish": false,
    "service": "twitter",
    "type": "twitter",
    "uri": "https://api.soundcloud.com/connections/310235"
  },
  {
    "created_at": "2010/12/04 02:28:11 +0000",
    "display_name": "First and last name",
    "id": 310234,
    "post_favorite": false,
    "post_publish": false,
    "service": "facebook_profile",
    "type": "facebook_profile",
    "uri": "https://api.soundcloud.com/connections/310234"
  },
  {
    "created_at": "2010/03/31 14:55:59 +0000",
    "display_name": "My Myspace Name",
    "id": 105941,
    "post_favorite": false,
    "post_publish": false,
    "service": "myspace",
    "type": "myspace",
    "uri": "https://api.soundcloud.com/connections/105941"
  }
]

/me/activities

The newest activities for the logged-in user

What are activities?

Activities are the items on your Dashboard. Currently the following activity types are supported:

Type Origin
track Track
track-sharing Track and Sharing-Note
comment Comment with Mini-User and Mini-Track
favoriting Mini-Track and Mini-User

Activities are always ordered by most recent activity first.

Representation

This is the general structure of activities (example: a comment on one of the users tracks):

$ curl -H 'Authorization: OAuth A_VALID_TOKEN' 'https://api.soundcloud.com/me/activities?limit=1'

{
  "next_href": "https://api.soundcloud.com/...?cursor=81923e19...",
  "collection": [
    {
      "type":       "comment",
      "created_at": "2011/07/21 09:55:19 +0000",
      "origin": {
        ...
      }
    },
    ...
  ]
}

Origin holds the objects the activity happend on.

Pagination

You can limit the number of activities by using the limit query parameter.

Every collection of activities includes a link to the next collection of activities (if such a collection exists) with the next_href property. The next_href property will be a URI with a cursor parameter that can be used to fetch the next page of results. The future_href property can be used to poll for updated results.

Resources

Methods Path Description
GET /me/activities Recent activities
GET /me/activities/tracks Recent track related activities (liked/reposted/uploaded)
GET /me/activities/all/own Recent activities on the logged-in users tracks

/resolve

The resolve resource allows you to lookup and access API resources when you only know the SoundCloud.com URL.

Example

$ curl -v 'https://api.soundcloud.com/resolve?url=https://soundcloud.com/matas/hobnotropic&client_id=YOUR_CLIENT_ID'

< HTTP/1.1 302 Moved Temporarily
< Location: https://api.soundcloud.com/tracks/49931

This request will resolve and redirect to the API resource URL for the track https://soundcloud.com/matas/hobnotropic. Just follow the redirect and you will get the representation you want. The resolver supports URLs for:

  • users
  • tracks
  • playlists (sets)

/oembed

oEmbed is an open standard to easily embed content from oEmbed providers into your site. The SoundCloud oEmbed endpoint will serve the widget embed code for any SoundCloud URL pointing to a user, set, or a playlist. To find out more about the oEmbed standard, have a look at oEmbed.com.

$ curl "https://soundcloud.com/oembed" \\           -d 'format=json' \\           -d 'url=https://soundcloud.com/forss/flickermood'
{
  "version": 1.0,
  "type": "rich",
  "provider_name": "Soundcloud",
  "provider_url": "https://soundcloud.com",
  "height": 81,
  "width": "100%",
  "title": "Flickermood by Forss",
  "description": "test",
  "html": "test"
}

Parameters

Name Default Description
url - A Soundcloud URL for a track, set, user.
format json (optional) Either json or js (for JSONP).
callback - (optional) A function name for the JSONP callback .
maxwidth 100% (optional) The maximum width in px.
maxheight 166 or 450 (optional) The maximum height in px. The default is 166px for tracks and 450px for sets. If using the flash widget, the default is 81px for tracks and 305px for sets.
color - (optional) The primary color of the widget as a hex triplet. (For example: ff0066).
auto_play false (optional) Whether the widget plays on load.
show_comments true (optional) Whether the player displays timed comments.
iframe true (optional) Whether the new HTML5 Iframe-based Widget or the old Adobe Flash Widget will be returned.