Introduction
The SoundCloud API is built with the design principles of REST in mind, exposing SoundCloud resources like tracks, sets and users which can be accessed and manipulated using the HTTP methods GET, POST, PUT and DELETE. We aim to provide all features which are available on SoundCloud.com itself through the API as well.
All SoundCloud resources are accessed and manipulated in a similar way.
A list of the latest resources 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].
To start using the API, you’ll first need to register an app. Once created you can use the client_id of your new app to do public API calls:
$ curl "http://api.soundcloud.com/tracks.json?client_id=YOUR_CLIENT_ID&limit=10"
[
{
"id": 8858260,
"created_at": "2011/01/08 01:01:25 +0000",
"user_id": 2034486,
"duration": 153422,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "",
"permalink": "buzweidah-w-i-p",
"description": "",
"streamable": true,
"downloadable": false,
"genre": "Dubstep",
"release": "",
"purchase_url": null,
"label_id": null,
"label_name": "",
"isrc": "",
"video_url": null,
"track_type": "",
"key_signature": "",
"bpm": null,
"playback_count": 0,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "BUZWEIDAH (W.I.P)",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "mp3",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858260",
"permalink_url": "http://soundcloud.com/blak_powdah/buzweidah-w-i-p",
"artwork_url": null,
"waveform_url": "http://waveforms.soundcloud.com/ewQFlYUwNy0F_m.png",
"user": {
"id": 2034486,
"permalink": "blak_powdah",
"username": "Blak-Powdah",
"uri": "http://api.soundcloud.com/users/2034486",
"permalink_url": "http://soundcloud.com/blak_powdah",
"avatar_url": "http://i1.soundcloud.com/avatars-000001985627-v0v3pd-large.jpg?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858260/stream",
"attachments_uri": "http://api.soundcloud.com/tracks/8858260/attachments"
},
{
"id": 8858254,
"created_at": "2011/01/08 01:01:14 +0000",
"user_id": 2635789,
"duration": 4799267,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "",
"permalink": "dj-tofix",
"description": "",
"streamable": true,
"downloadable": false,
"genre": "House",
"release": "",
"purchase_url": null,
"label_id": null,
"label_name": "",
"isrc": "",
"video_url": null,
"track_type": "",
"key_signature": "",
"bpm": null,
"playback_count": 0,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "Dj tofix",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "mp3",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858254",
"permalink_url": "http://soundcloud.com/dj-tofix/dj-tofix",
"artwork_url": "http://i1.soundcloud.com/artworks-000004001457-uwub5z-large.jpg?3e8e24",
"waveform_url": "http://waveforms.soundcloud.com/TrsVPF66ULCp_m.png",
"user": {
"id": 2635789,
"permalink": "dj-tofix",
"username": "dj tofix",
"uri": "http://api.soundcloud.com/users/2635789",
"permalink_url": "http://soundcloud.com/dj-tofix",
"avatar_url": "http://a1.soundcloud.com/images/default_avatar_large.png?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858254/stream",
"attachments_uri": "http://api.soundcloud.com/tracks/8858254/attachments"
},
{
"id": 8858253,
"created_at": "2011/01/08 01:01:12 +0000",
"user_id": 1362435,
"duration": 118327,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "",
"permalink": "oh-no-master",
"description": "",
"streamable": true,
"downloadable": false,
"genre": "",
"release": "",
"purchase_url": null,
"label_id": null,
"label_name": "",
"isrc": "",
"video_url": null,
"track_type": "",
"key_signature": "",
"bpm": null,
"playback_count": 1,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "Oh no master",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "mp3",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858253",
"permalink_url": "http://soundcloud.com/jamesevanstech/oh-no-master",
"artwork_url": null,
"waveform_url": "http://waveforms.soundcloud.com/7LbGoKT8oUfs_m.png",
"user": {
"id": 1362435,
"permalink": "jamesevanstech",
"username": "Jamesevanstech",
"uri": "http://api.soundcloud.com/users/1362435",
"permalink_url": "http://soundcloud.com/jamesevanstech",
"avatar_url": "http://i1.soundcloud.com/avatars-000002300300-ceijfl-large.jpg?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858253/stream",
"attachments_uri": "http://api.soundcloud.com/tracks/8858253/attachments"
},
{
"id": 8858251,
"created_at": "2011/01/08 01:01:08 +0000",
"user_id": 1535179,
"duration": 51219,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "",
"permalink": "gld4-preview",
"description": "",
"streamable": true,
"downloadable": false,
"genre": "",
"release": "",
"purchase_url": null,
"label_id": null,
"label_name": "",
"isrc": "",
"video_url": null,
"track_type": "",
"key_signature": "",
"bpm": null,
"playback_count": 0,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "GLD4 preview",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "mp3",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858251",
"permalink_url": "http://soundcloud.com/cantcatchthecrooks/gld4-preview",
"artwork_url": null,
"waveform_url": "http://waveforms.soundcloud.com/RSqnRLpFj64g_m.png",
"user": {
"id": 1535179,
"permalink": "cantcatchthecrooks",
"username": "CANTCATCHTHECROOKS",
"uri": "http://api.soundcloud.com/users/1535179",
"permalink_url": "http://soundcloud.com/cantcatchthecrooks",
"avatar_url": "http://i1.soundcloud.com/avatars-000001610720-yo203n-large.jpg?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858251/stream",
"attachments_uri": "http://api.soundcloud.com/tracks/8858251/attachments"
},
{
"id": 8858248,
"created_at": "2011/01/08 01:01:02 +0000",
"user_id": 2640239,
"duration": 49520,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "soundcloud:source=iphone-record",
"permalink": "fail-1-on-saturday-morning",
"description": null,
"streamable": true,
"downloadable": false,
"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,
"playback_count": 0,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "Fail 1 on Saturday morning",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "m4a",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858248",
"permalink_url": "http://soundcloud.com/ohsofamous/fail-1-on-saturday-morning",
"artwork_url": null,
"waveform_url": "http://waveforms.soundcloud.com/Z371moiheBuu_m.png",
"user": {
"id": 2640239,
"permalink": "ohsofamous",
"username": "ohsofamous",
"uri": "http://api.soundcloud.com/users/2640239",
"permalink_url": "http://soundcloud.com/ohsofamous",
"avatar_url": "http://i1.soundcloud.com/avatars-000002377055-oh0ueb-large.jpg?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858248/stream",
"created_with": {
"id": 124,
"name": "SoundCloud iPhone",
"uri": "http://api.soundcloud.com/apps/124",
"permalink_url": "http://soundcloud.com/apps/iphone"
},
"attachments_uri": "http://api.soundcloud.com/tracks/8858248/attachments"
},
{
"id": 8858247,
"created_at": "2011/01/08 01:00:59 +0000",
"user_id": 1547478,
"duration": 1830417,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "",
"permalink": "dj-zee-drift-house-mix",
"description": "",
"streamable": true,
"downloadable": true,
"genre": "",
"release": "",
"purchase_url": null,
"label_id": null,
"label_name": "",
"isrc": "",
"video_url": null,
"track_type": "",
"key_signature": "",
"bpm": null,
"playback_count": 1,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "DJ ZEE- Drift House Mix",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "raw",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858247",
"permalink_url": "http://soundcloud.com/deejayzee/dj-zee-drift-house-mix",
"artwork_url": null,
"waveform_url": "http://waveforms.soundcloud.com/8gBbWj2nVcuy_m.png",
"user": {
"id": 1547478,
"permalink": "deejayzee",
"username": "Dj.Zee",
"uri": "http://api.soundcloud.com/users/1547478",
"permalink_url": "http://soundcloud.com/deejayzee",
"avatar_url": "http://i1.soundcloud.com/avatars-000001622459-enu33k-large.jpg?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858247/stream",
"download_url": "http://api.soundcloud.com/tracks/8858247/download",
"attachments_uri": "http://api.soundcloud.com/tracks/8858247/attachments"
},
{
"id": 8858245,
"created_at": "2011/01/08 01:00:57 +0000",
"user_id": 1354566,
"duration": 288291,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "",
"permalink": "hugasawa",
"description": "",
"streamable": true,
"downloadable": true,
"genre": "Downtempo",
"release": "",
"purchase_url": null,
"label_id": null,
"label_name": "",
"isrc": "",
"video_url": null,
"track_type": "",
"key_signature": "",
"bpm": null,
"playback_count": 0,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "Hugasawa",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "wav",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858245",
"permalink_url": "http://soundcloud.com/krystofos/hugasawa",
"artwork_url": null,
"waveform_url": "http://waveforms.soundcloud.com/gb1Iu9xCUCvJ_m.png",
"user": {
"id": 1354566,
"permalink": "krystofos",
"username": "krystofos",
"uri": "http://api.soundcloud.com/users/1354566",
"permalink_url": "http://soundcloud.com/krystofos",
"avatar_url": "http://i1.soundcloud.com/avatars-000001535944-qwcfnp-large.jpg?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858245/stream",
"download_url": "http://api.soundcloud.com/tracks/8858245/download",
"attachments_uri": "http://api.soundcloud.com/tracks/8858245/attachments"
},
{
"id": 8858244,
"created_at": "2011/01/08 01:00:56 +0000",
"user_id": 223044,
"duration": 275278,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "",
"permalink": "sencae",
"description": "",
"streamable": true,
"downloadable": false,
"genre": "Breakbeat",
"release": "",
"purchase_url": null,
"label_id": null,
"label_name": "",
"isrc": "",
"video_url": null,
"track_type": "",
"key_signature": "",
"bpm": 0.0,
"playback_count": 0,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "Sencae - ???",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "mp3",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858244",
"permalink_url": "http://soundcloud.com/djsencae/sencae",
"artwork_url": null,
"waveform_url": "http://waveforms.soundcloud.com/3wZIqRlB03sn_m.png",
"user": {
"id": 223044,
"permalink": "djsencae",
"username": "djsencae",
"uri": "http://api.soundcloud.com/users/223044",
"permalink_url": "http://soundcloud.com/djsencae",
"avatar_url": "http://i1.soundcloud.com/avatars-000001050472-6uil5h-large.jpg?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858244/stream",
"attachments_uri": "http://api.soundcloud.com/tracks/8858244/attachments"
},
{
"id": 8858243,
"created_at": "2011/01/08 01:00:56 +0000",
"user_id": 1100398,
"duration": 60652,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "soundcloud:source=web-record",
"permalink": "audio-recording-on-friday-afternoon-10",
"description": "Ciao Olga",
"streamable": true,
"downloadable": true,
"genre": "",
"release": "",
"purchase_url": null,
"label_id": null,
"label_name": "",
"isrc": "",
"video_url": null,
"track_type": "recording",
"key_signature": "",
"bpm": null,
"playback_count": 0,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "Audio Recording on Friday afternoon",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "wav",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858243",
"permalink_url": "http://soundcloud.com/user2172490/audio-recording-on-friday-afternoon-10",
"artwork_url": "http://i1.soundcloud.com/artworks-000004001875-zm1sst-large.jpg?3e8e24",
"waveform_url": "http://waveforms.soundcloud.com/rDVmNER2hcRJ_m.png",
"user": {
"id": 1100398,
"permalink": "user2172490",
"username": "user2172490",
"uri": "http://api.soundcloud.com/users/1100398",
"permalink_url": "http://soundcloud.com/user2172490",
"avatar_url": "http://i1.soundcloud.com/avatars-000002359828-tcuhoy-large.jpg?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858243/stream",
"download_url": "http://api.soundcloud.com/tracks/8858243/download",
"attachments_uri": "http://api.soundcloud.com/tracks/8858243/attachments"
},
{
"id": 8858242,
"created_at": "2011/01/08 01:00:55 +0000",
"user_id": 56601,
"duration": 597778,
"commentable": true,
"state": "finished",
"sharing": "public",
"tag_list": "UFO! BASS REVILATON UFOCREEPMUSIC",
"permalink": "revelation-ep-sampler",
"description": "Revelation will be available on January 11, 2011 on www.ufocreepmusic.bandcamp.com",
"streamable": true,
"downloadable": false,
"genre": "BASS",
"release": "",
"purchase_url": null,
"label_id": null,
"label_name": "",
"isrc": "",
"video_url": null,
"track_type": "original",
"key_signature": "",
"bpm": null,
"playback_count": 0,
"download_count": 0,
"comment_count": 0,
"favoritings_count": 0,
"title": "REVELATION EP SAMPLER",
"release_year": null,
"release_month": null,
"release_day": null,
"original_format": "mp3",
"original_content_size": 10211857,
"license": "all-rights-reserved",
"uri": "http://api.soundcloud.com/tracks/8858242",
"permalink_url": "http://soundcloud.com/ufo55555/revelation-ep-sampler",
"artwork_url": "http://i1.soundcloud.com/artworks-000004001883-34mwaq-large.jpg?3e8e24",
"waveform_url": "http://waveforms.soundcloud.com/uAjk7LgNADPn_m.png",
"user": {
"id": 56601,
"permalink": "ufo55555",
"username": "ufo55555",
"uri": "http://api.soundcloud.com/users/56601",
"permalink_url": "http://soundcloud.com/ufo55555",
"avatar_url": "http://i1.soundcloud.com/avatars-000001926314-ksibbh-large.jpg?3e8e24"
},
"stream_url": "http://api.soundcloud.com/tracks/8858242/stream",
"attachments_uri": "http://api.soundcloud.com/tracks/8858242/attachments"
}
]
This cURL example will do a GET request on /tracks.json and pass the parameters client_id and limit. If you have the cURL tool installed you can replace the client_id parameter with your own and run this example in your terminal or use our API Console.
Lets examine the request:
The appended .json specifies that the response format should be JSON.
If not specified the format will default to XML. However we encourage you to use JSON and accordingly all examples in this documentation will use JSON.
You can also specify the response format using the HTTP Accept header (Accept: application/json)
or by passing a format parameter:
http://api.soundcloud.com/tracks?client_id=#{client_id}&limit=10&format=json
The first parameter client_id=YOUR_CLIENT_ID is passed to authenticate as an app. The examples in the documentation will always use YOUR_CLIENT_ID. Please replace this with your own client id.
An exception for the client_id requirement is when a valid OAuth access token is passed. This means that you are doing API calls for a SoundCloud user who delegated access to your app. This is described in the next section Authentication.
The next parameter is limit=10. It will limit the returned collection to 10 tracks instead of the default of 50 tracks. Read more about pagination and collections here.
The response itself is a JSON array of track objects. Each object holds a bunch of attributes like title, duration and permalink_url for example. The track attributes and subresources are described in detail in the /tracks section.
Have a look at Creating a comment and Updating a user to see how resources are manipulated.
This was a first introduction to the SoundCloud API. Continue and have a closer look at the available resources like /users, /tracks and /groups or find out how the /authentication works. Also check out the SDKs that could help you building your app. If you haven't found the answer to your question checkout the Q&As and comments at the end of each section or get in touch with us.
Which response formats are supported?
We support xml, json and jsonp. The requested format can be specified by passing a format parameter:
$ curl "http://api.soundcloud.com/users?client_id=YOUR_CLIENT_ID&format=xml"Or by setting the HTTP Accept header:
$ curl -H "Accept: application/json" "http://api.soundcloud.com/users?client_id=YOUR_CLIENT_ID"Or by appending .format to the resource path:
$ curl http://api.soundcloud.com/users.json?client_id=YOUR_CLIENT_IDWe also support JSONP. Just request JSON and pass a callback parameter:
$ curl "http://api.soundcloud.com/users?client_id=YOUR_CLIENT_ID&format=json&callback=YOUR_CALLBACK"Are Cross Domain Requests using CORS or JSONP supported?
Yes both are supported.
To use JSONP just request JSON and pass a callback parameter:
curl "http://api.soundcloud.com/users.json?client_id=YOUR_CLIENT_ID&callback=FUNCTION_NAME"We also support CORS, a new emerging standard that is implemented in most modern browsers, to work around cross domain restrictions.
How does the pagination work?
All collections are limited to 50 items by default. This can be overridden by passing a
limitparameter. You can paginate through a collections by passing anoffsetparameter and incrementing it by the limit for each request:curl "http://api.soundcloud.com/users/183/tracks.json?client_id=YOUR_CLIENT_ID&limit=50&offset=0" curl "http://api.soundcloud.com/users/183/tracks.json?client_id=YOUR_CLIENT_ID&limit=50&offset=50" curl "http://api.soundcloud.com/users/183/tracks.json?client_id=YOUR_CLIENT_ID&limit=50&offset=100"Once you receive 0 items you can assume that you've reached the end of the collection. The maxium value is 200 for
limitand 8000 foroffset.Where can I test my apps?
We recommend to do your development against api.soundcloud.com, as long as you don't interfere with other SoundCloud user.
There is a sandbox available on http://sandbox-soundcloud.com, which is an older snapshot of the live database where we sometimes prerelease certain API features before they are available on the live site.
Be aware that we occasionally reset the sandbox database, so don't expect any data to be forever.
How does the error handling work?
Errors are reported through the HTTP status code and optionally additional information in the body. For example:
$ curl -i http://api.soundcloud.com/groups.json HTTP/1.1 401 Unauthorized Content-Type: application/json; charset=utf-8 Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, PUT, POST, DELETE Access-Control-Allow-Headers: Authorization, Content-Type, Accept Content-Length: 52 {"errors": [{"error_message": "401 - Unauthorized"}]}Common errors are:
400 Bad Request Check if your request is a valid HTTP request. 401 Unauthorized Check if you've send a valid client_id or access_token. 403 Forbidden Access to the requested resource is forbidden. 404 Not Found The requested resource was not found or is not accessible to the user. 406 Not Acceptable The resource is not available in the format you requested. 422 Unprocessable Entity The request is syntaxtically correct, but of an incorrect structure for this resource. Typically you are missing required properties or use incorrect data structures (e.g. strings instead of arrays). 500 Internal Server Error Occurs when an unexpected error on our side happend. Please contact us to resolve that issue. 503 Service Unavailable Occurs when no services are available to process your request. If possible provide your app users a way to manually trigger a retry. 504 Gateway Timeout Occurs when the request processing took to long. Be aware that your request could still be executed and manipulate data.