HTTP API Guide
Using the SoundCloud API, you can build applications that take sound on the web to the next level. With this guide we explain and provide code examples for many common integration use cases like playing and uploading sounds or how to take advantage of SoundCloud's many social features. If you're looking for more in depth information, feel free to jump to our API Reference.
To help you get started quickly, SDKs are available for Python, Ruby, JavaScript. To follow along with the examples below, you'll need to have at least one SDK installed.
Now go ahead and jump to the section you're most interested in and get started.
- Sign in with SoundCloud
- Client-side JavaScript Applications
- Server-side Web Applications
- Mobile and Desktop Applications
- Getting Information about Authenticated User
- Authenticating without the SoundCloud Connect Screen
- Refreshing Tokens
- Uploading Audio Files
- Updating Metadata
- Sharing Sounds to other Social Networks
- Creating Sets
- Adding Sounds to a Set
- Accessing Sets
Authentication
Uploading Sounds
Playing Sounds
Follow & Like
Search
Pagination
SoundCloud URLs
Cross Domain Requests
Errors
Authentication
This section presumes you have:
Our API allows you to get permission from a SoundCloud user to access SoundCloud on their behalf. This means that you will have access to their account, including any private sounds or sets that they have created or have had shared with them. You can also use SoundCloud for your app's registration and sign-in process. This creates a seamless, one click experience for your users and give your app an easy way to upload sounds, make comments or otherwise act on a user's behalf.
SoundCloud authentication uses OAuth 2.0, a popular open standard used by many popular API providers. OAuth 2.0 allows users to authorize your application without disclosing their username and password.
There are different ways to authenticate with OAuth, depending on the type of application you're building. You can also simplify your login process by using the Connect with SoundCloud buttons as your apps login system.
In this section:
Sign in with SoundCloud
You can simplify your registration and sign in process by using a Connect with SoundCloud button. This lets your user know that they can register for your app with one click using their SoundCloud account. It also grants your app access to their account and gives you the ability to upload tracks, create sets and otherwise act on their behalf.
Client-side JavaScript Applications
If you are writing an application that runs in the browser, you
should use the JavaScript SDK SC.connect()
method to
authenticate your app.
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
client_id: 'YOUR_CLIENT_ID',
redirect_uri: 'https://example.com/callback'
});
// initiate auth popup
SC.connect().then(function() {
return SC.get('/me');
}).then(function(me) {
alert('Hello, ' + me.username);
});
</script>
A pop-up window will be opened allowing the user to log in to
SoundCloud and approve your app's authorization request. You'll have
to host the callback.html
file on your server and set the redirect_uri
in your app settings
accordingly.
Try out the Client-side auth flow
Security Advice
Using the implicit
OAuth authorization flow (response_type=token
) is response_type=code
instead.
Use the state
parameter for
CSRF protection. Pass a sufficient random nonce here and verify this nonce again
after retrieving the token.
Server-side Web Applications
To authenticate your server-side web application using one of our
SDKs, create an instance of the Soundcloud
class with
the API credentials you obtained when you registered your app and
redirect the user to the authorization URL so that they can log in
and approve your request.
require 'soundcloud' # create client object with app credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID', :client_secret => 'YOUR_CLIENT_SECRET', :redirect_uri => 'https://example.com/callback') # redirect user to authorize URL redirect_to client.authorize_url()
import soundcloud # create client object with app credentials client = soundcloud.Client(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', redirect_uri='https://example.com/callback') # redirect user to authorize URL redirect client.authorize_url()
// this example is not applicable to the JavaScript SDK
The user will be redirected to a SoundCloud connect screen and asked to authorize your application. If the user is already signed into SoundCloud, they will be able to authorize your request in one click.

If the user approves your authorization request, they will be sent
to the redirect_uri
you specified when registering your app. Extract
the code parameter from the query string and use it to obtain an
access token.
require 'soundcloud' # create client object with app credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID', :client_secret => 'YOUR_CLIENT_SECRET', :redirect_uri => 'https://example.com/callback') # exchange authorization code for access token code = params[:code] access_token = client.exchange_token(:code => code)
import soundcloud # create client object with app credentials client = soundcloud.Client(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', redirect_uri='https://example.com/callback') # exchange authorization code for access token code = params['code'] access_token = client.exchange_token(code)
// this example is not applicable to the JavaScript SDK
You should now store the access token in a database. Associate it
with the user it belongs to and use it from now on instead of
sending the user through the authorization flow. The returned object
will have an access_token
property and a refresh_token
property as well as expires_in
and scope
.
require 'soundcloud' # create client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # make an authenticated call current_user = client.get('/me') puts current_user.username
import soundcloud # create client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # make an authenticated call current_user = client.get('/me') print current_user.username
// this example is not applicable to the JavaScript SDK
Refreshing Tokens
You will need to periodically refresh your access tokens when they expire:
require 'soundcloud' # create client object with app credentials and refresh token client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID', :client_secret => 'YOUR_CLIENT_SECRET', :refresh_token => 'SOME_REFRESH_TOKEN') # the client can now be used to make authenticated API calls puts client.get('/me').username
import soundcloud # create client object with app credentials and refresh token client = Soundcloud.new(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', refresh_token='SOME_REFRESH_TOKEN') # the client can now be used to make authenticated API calls print client.get('/me').username
// this example is not applicable to the JavaScript SDK
Mobile and Desktop Applications
You authenticate Mobile and Desktop Applications the same way you
do for Server-side Web Applications. To make the flow smoother, you
can use a redirect_uri
with a custom protocol scheme and set your
app as a handler for that protocol scheme. For example, your
redirect_uri
could be something like my-app://soundcloud/callback
.
When building apps for mobile devices, we recommend using our
mobile optimized connect screen by setting display=popup
in the authorization URL query string.

Getting Information about the Authenticated User
Once the user has signed into SoundCloud and approved your app's authorization request, you will be able to access their profile and act on their behalf. We have provided a convenient endpoint for accessing information about the authenticated user.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # print out the user's username puts client.get('/me').username # update the user's profile description user = client.post('/me', :description => 'I am using the SoundCloud API!') puts user.description
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # print out the user's username print client.get('/me').username # update the user's profile description user = client.post('/me', description='I am using the SoundCloud API!') print user.description
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); // update user's profile description SC.connect().then(function() { SC.put('/me', { user: { description: 'I am using the SoundCloud API!' } }); }); </script>
Authenticating without the SoundCloud Connect Screen
If you simply need an access token for testing, and do not want to go through the connect flow, or if you have one central account your app needs to access, you can use the OAuth User Credentials Flow. An example of this kind of app would be an artist's website where you'll only be using a single SoundCloud account for the artists sets, user information and sounds. In these cases you may exchange a set of user credentials for an access token.
Do not use this if you intend for users to access their SoundCloud accounts from your app. Because this authorization flow depends on passing a set of user credentials, it is inaccessible for anyone who has used Facebook Connect to create their SoundCloud account. It is also a bad practice to require users to give your app their user credentials. If you intend to upload sounds from different users, you must use a more appropriate authentication flow, such as the ones explained above.
Our Terms of Service specify that you must use the Connect with SoundCloud screen unless you have made a separate arrangement with us.
require 'soundcloud' # create client object with app and user credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID', :client_secret => 'YOUR_CLIENT_SECRET', :username => 'YOUR_USERNAME', :password => 'YOUR_PASSWORD') # print authenticated user's username puts client.get('/me').username
import soundcloud # create client object with app and user credentials client = soundcloud.Client(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', username='YOUR_USERNAME', password='YOUR_PASSWORD') # print authenticated user's username print client.get('/me').username
// this example is not supported by the JavaScript SDK
Uploading Sounds
This section presumes you have:
Sounds (in the API these are called tracks) are core to SoundCloud. Our API gives you the ability to upload, manage and share sounds on the web. Your app can take an audio file and upload it to a user's SoundCloud account. You can also manage metadata (including tags), share the sound on other social networks, or add the sound to playlists. We support the following formats: AIFF, WAVE, FLAC, OGG, MP2, MP3, AAC, AMR and WMA.
In this section:
Uploading Audio Files
To upload a sound, send a POST request with a multipart/form-data
media type
to the /tracks
endpoint. This is done with one of our SDKs using the post
method
and passing information about the track being uploaded.
Request bodies for track uploads via the API may not be larger than 500MB.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # upload an audio file track = client.post('/tracks', :track => { :title => 'This is my sound', :asset_data => File.new('file.mp3', 'rb') }) # print track link puts track.permalink_url
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # upload audio file track = client.post('/tracks', track={ 'title': 'This is my sound', 'asset_data': open('file.mp3', 'rb') }) # print track link print track.permalink_url
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> // When you have recorded a song with the SDK or any Web Audio application, // you can upload it if it's in a format that is accepted SC.upload({ file: theBlob, // a Blob of your WAV, MP3... title: 'This is my sound' }); </script>
If successful, your track will immediately be queued up for
encoding. You check the state
property of the track resource to
check its progress. Once the state is finished
it is ready to be
embedded or streamed.
See also:
- /tracks endpoint reference documentation.
- Desktop sharing kits.
- iOS sharing kit.
- Android sharing kit.
Updating Metadata
In order to update a sounds metadata, you create a client and call
the put
method, passing in the path of the track resource and the
properties you want to update.
You can update the track artwork using the artwork_data
parameter.
Please note that at this time it is not possible to update the actual track audio
file.
For a full list of properties that can be set on a sound resource, see the /tracks endpoint reference.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # fetch a track by it's ID track = client.get('/tracks/290') # update the track's metadata client.put(track.uri, :track => { :description => 'This track was recorded in Berlin', :genre => 'Electronic', :artwork_data => File.new('artwork.jpg', 'rb') })
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # fetch a track by it's ID track = client.get('/tracks/290') # update the track's metadata client.put(track.uri, track={ 'description': 'This track was recorded in Berlin', 'genre': 'Electronic', 'artwork_data': open('artwork.jpg', 'rb') })
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); var getTracks = function() { return SC.get('/me/tracks'); }; // connect and update track data SC.connect().then(getTracks).then(function(tracks){ SC.put('/tracks' + tracks[0].id, { track: { description: 'This track was recorded in Berlin', genre: 'Electronic' } }); }); </script>
Sharing Sounds to other Social Networks
SoundCloud accounts can be connected to accounts on Twitter, Facebook, Foursquare and Tumblr to allow easy sharing of tracks and favorites. On every public track your app uploads, you can choose to share it to one of the connected social networks.
A list of networks that a user has connected to their account is available using the /me/connections endpoint. You can create new connections, and use existing connections to share tracks and playlists using our API.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # get a list of connected social networks connections = client.get('/me/connections') # print out connection details connections.each do |connection| puts "Connection type: #{connection.type}" puts "Favorites are posted to this network" if connection.post_favorite puts "New tracks and playlists are shared" if connection.post_publish end
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # get a list of connected social networks connections = client.get('/me/connections') # print out connection details for connection in connections: print "Connection type: %s" % connection.type if connection.post_favorite: print "Favorites are posted to this network" if connection.post_publish: print "New sounds and sets are shared"
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); // list connected social networks SC.connect().then(function() { SC.get('/me/connections').then(function(connection) { alert('Connection id: ' + connection.id); }); }); </script>
When you upload new sounds or create a new set, you can automatically share to Twitter, Facebook or any other network connected to your apps users SoundCloud account.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # get 'twitter' connection connection = client.get('/me/connections').find { |c| c.type == 'twitter' } # upload new track and share it on twitter track = client.post('/tracks', :track => { :title => 'This is my new sound', :asset_data => File.new('audio.mp3', 'rb'), :shared_to => { :connections => [{:id => connection.id}] } })
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # get 'twitter' connection connection = [c for c in client.get('/me/connections') if c.type == 'twitter'][0] # upload new track and share it on twitter track = client.post('/tracks', track={ 'title': 'This is my new sound', 'asset_data': open('audio.mp3', 'rb'), 'shared_to': [{'id': connection.id}] })
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); var recorder = new SC.Recorder(); var startRecording = function () { recorder.start(); setTimeout(stopRecordingAndUpload, 5000); }; var stopRecordingAndUpload = function () { recorder.stop(); recorder.getWAV().then(function(wav){ SC.upload({ file: wav, title: 'track' + Date.now(), connections: [ { id: 123 } ] // the desired connection to share to }); }); }; SC.connect().then(startRecording); </script>
You can also share an existing track or playlist.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # get 'twitter' connection connection = client.get('/me/connections').find { |c| c.type == 'twitter' } # share sound on twitter client.post("/tracks/#{track.id}/shared-to/connections", :connections => [{:id => connection.id}], :sharing-note => 'Check out my new sound' )
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # get 'twitter' connection connection = [c for c in client.get('/me/connections') if c.type == 'twitter'][0] # share sound on twitter client.post("/tracks/#{track.id}/shared-to/connections", connections=[{'id': connection.id}], sharing-note='Check out my new sound' )
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); var getConnections = function () { return SC.get('/me/connections'); }; SC.connect().then(getConnections).then(function(connections){ SC.post('/tracks/THE_TRACK_ID/shared-to/connections', { connections: [ { id: connections[0].id } ], sharing-note: 'Check out my new sound' }); }); </script>
See also:
- /tracks endpoint reference documentation
- /me/connections endpoint reference documentation
- Desktop sharing kits
- iOS sharing kit
- Android sharing kit
Creating Sets
Sets (in the API these are called playlists) allow you to organize sounds into groups that can be shared together. For example, songs in an album or a specific collection of sounds can be grouped together using a set and then shared to the world. You can only add sounds that you own to a set and a sound can belong to multiple sets.
You create sets using our API by creating a client and calling the post method with the /playlists endpoint and information about the set, including a list of track ids.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # create an array of track ids tracks = [290, 291, 292].map { |id| {:id => id} } # create the playlist client.post('/playlists', :playlist => { :title => 'My new album', :sharing => 'public', :tracks => tracks })
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # create an array of track ids tracks = map(lambda id: dict(id=id), [290, 291, 292]) # create the playlist client.post('/playlists', playlist={ 'title': 'My new album', 'sharing': 'public', 'tracks': tracks })
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); var tracks = [{id: 290}, {id: 291}, {id: 292}]; SC.connect().then(function() { SC.post('/playlists', { playlist: { title: 'My Playlist', tracks: tracks } }); }); </script>
Adding Sounds to a Set
Once a set has been created, you can continue to add sounds to it by
updating the tracks
property.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # create an array of track ids tracks = [290, 291, 292].map { |id| {:id => id} } # get playlist playlist = client.get('/me/playlists').first # add tracks to playlist client.put(playlist.uri, :playlist => { :tracks => tracks })
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # create an array of track ids tracks = map(lambda id: dict(id=id), [290, 291, 292]) # get playlist playlist = client.get('/me/playlists')[0] # add tracks to playlist client.put(playlist.uri, playlist={ 'tracks': tracks })
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); var tracks = [{id: 290}, {id: 291}, {id: 292}]; var getFirstPlaylist = function() { return SC.get('/me/playlists', { limit: 1 }); }; var addTracks = function(playlists) { return SC.put('/playlists/' + playlists[0].id, { playlist: { tracks: tracks } }); }; SC.connect().then(getFirstPlaylist).then(addTracks); </script>
Accessing Sets
To get a list of tracks in a set, send a GET request to the /playlists endpoint with the set id.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # get playlist playlist = client.get('/playlists/2050462') # list tracks in playlist playlist.tracks.each do |track| puts track.title end
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # get playlist playlist = client.get('/playlists/2050462') # list tracks in playlist for track in playlist.tracks: print track['title']
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID' }); SC.get('/playlists/2050462').then(function(playlist) { playlist.tracks.forEach(function(track) { console.log(track.title); }); }); </script>
See also:
- /playlists endpoint reference documentation.
Playing Sounds
This section presumes you have:
Yep, you can also play sounds from your application. Depending on your needs, you can embed a player widget, use the JavaScript SDK to stream audio content in the browser, or feed a stream url into your own audio player. You can also use our Widget API to control the player and handle events.
In this section:
Embedding a SoundCloud Widget
If you have the URL of a sound or set, you can get the embed code and paste it into your website. You can also do this in your application using the oEmbed endpoint. Given a sound or set URL, you can retrieve all of the information you need to embed a player.
The JavaScript SDK has a shortcut for embedding a player widget. In
order to embed a player widget using the JavaScript SDK, you can
call the SC.oEmbed()
function, passing in the track or playlist URL
and any options for the player. For full details, see our
oEmbed reference.
require 'soundcloud' # create a client object with your app credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID') # get a tracks oembed data track_url = 'https://soundcloud.com/forss/flickermood' embed_info = client.get('/oembed', :url => track_url) # print the html for the player widget puts embed_info['html']
import soundcloud # create a client object with your app credentials client = soundcloud.Client(client_id='YOUR_CLIENT_ID') # get a tracks oembed data track_url = 'https://soundcloud.com/forss/flickermood' embed_info = client.get('/oembed', url=track_url) # print the html for the player widget print embed_info['html']
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID' }); var track_url = 'https://soundcloud.com/forss/flickermood'; SC.oEmbed(track_url, { auto_play: true }).then(function(oEmbed) { console.log('oEmbed response: ', oEmbed); }); </script>
Example SoundCloud Widget
Streaming Sounds
Note if you are going to stream from our API you need to attribute properly. Make sure you've read our Terms and Attribution Guidelines to make sure you treat our creators content correctly. When using a custom player you must:
- Credit the uploader as the creator of the sound
- Credit SoundCloud as the source by including one of the logos found here
- Link to the SoundCloud URL containing the work
- If the sound is private link to the profile of the creator
If you don't want to use the SoundCloud widget, our API gives you
the ability to access a sound's stream URL and use your own player
to play sounds from SoundCloud. In order to get a URL for streaming
a sound, you can request the appropriate resource and make note of
the stream_url
property. Send a GET request to that URL and
you will get a 302 - Found
redirect, which you can intercept by
passing allow_redirects=False
to the get
method.
Note that as long as the sound is public, you'll only need to
provide a client_id
when creating a client. If you would like to
access the stream URL for a private sound, you'll need to
authenticate your app.
require 'soundcloud' # create a client object with your app credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID') # fetch track to stream track = client.get('/tracks/293') # get the tracks streaming URL stream_url = client.get(track.stream_url, :allow_redirects => true) # print the tracks stream URL puts stream_url.location
import soundcloud # create a client object with your app credentials client = soundcloud.Client(client_id='YOUR_CLIENT_ID') # fetch track to stream track = client.get('/tracks/293') # get the tracks streaming URL stream_url = client.get(track.stream_url, allow_redirects=False) # print the tracks stream URL print stream_url.location
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID' }); // stream track id 293 SC.stream('/tracks/293').then(function(player){ player.play().then(function(){ console.log('Playback started!'); }).catch(function(e){ console.error('Playback rejected. Try calling play() from a user interaction.', e); }); }); </script>
See also:
- /oembed endpoint reference documentation.
- HTML5 Widget API.
- JavaScript SDK Streaming.
- /tracks endpoint reference documentation.
Comments
This section presumes you have:
SoundCloud has many social features that make it easier to collaborate, share and get feedback. The primary way that SoundCloud users interact is by leaving comments on each other's sounds.
Our API allows you to leave comments on sounds by calling the
post
method with the /tracks/{TRACK_ID}/comments
path and
information about the comment. Include the timestamp to make it a
timed comment.
Note that you cannot leave comments on sounds if the creator has disabled comments.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # get the latest track from authenticated user track = client.get('/me/tracks', :limit => 1).first # create a new timed comment comment = client.post("/tracks/#{track.id}/comments", :comment => { :body => 'This is a timed comment', :timestamp => 1500 })
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # get the latest track from authenticated user track = client.get('/me/tracks', limit=1)[0] # create a new timed comment comment = client.post('/tracks/%d/comments' % track.id, comment={ 'body': 'This is a timed comment', 'timestamp': 1500 })
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); var commentOnTrack = function(tracks) { SC.post('/tracks/' + tracks[0].id + '/comments', { comment: { body: 'This is a timed comment', timestamp: 1500 } }); }; SC.connect().then(function() { SC.get('/me/tracks', { limit: 1 }).then(commentOnTrack); }); </script>
Note that the timestamp value is in milliseconds and represents the amount of time from the beginning of the sound. If you omit the timestamp, the comment will be a non-timed comment.
You can also get a list of comments for a specified sound.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # get the latest track from authenticated user track = client.get('/me/tracks', :limit => 1).first # get a list of comments for the track comments = client.get("/tracks/#{track.id}/comments") # print out each comment comments.each { |comment| puts comment.body }
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # get the latest track from authenticated user track = client.get('/me/tracks', limit=1)[0] # get a list of comments for the track comments = client.get('/tracks/%d/comments' % track.id) # print out each comment for comment in comments: print comment.body
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); var getTracks = function () { return SC.get('/me/tracks', { limit: 1 }); }; var getComments = function (tracks) { return SC.get('/tracks/' + tracks[0].id + '/comments'); }; var listComments = function (comments) { comments.forEach(function(comment){ console.log(comment.body) }) }; SC.connect().then(getTracks).then(getComments).then(listComments); </script>
See also:
- /tracks endpoint reference documentation.
Follow & Like
This section presumes you have:
Your application can take advantage of SoundCloud's social features by allowing users to follow other users and like sounds or sets. Following and liking allows SoundCloud users to customize their experience. Sounds created and reposted by people your user follows will be available in their activity feed.
You can follow a user using the /me/followings endpoint.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # Follow user with ID 3207 client.put('/me/followings/3207') # Unfollow the same user client.delete('/me/followings/3207') # check the status of the relationship begin client.get('/me/followings/3207') rescue Soundcloud::ResponseError => e if e.response.status == '404' puts 'You are not following user 3207' end end
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # Follow user with ID 3207 client.put('/me/followings/3207') # Unfollow the same user client.delete('/me/followings/3207') # check the status of the relationship try: client.get('/me/followings/3207') except Exception, e: if e.response.status == '404': print 'You are not following user 3207'
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); SC.connect().then(function() { // Follow user with ID 3207 SC.put('/me/followings/3207').then(function(){ // Unfollow the same user SC.delete('/me/followings/3207'); }); }); </script>
Liking a sound or set is done using the /me/favorites endpoint.
require 'soundcloud' # create a client object with access token client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN') # Fetch a track by it's ID track = client.get('/tracks/290') # Like the track client.put("/me/favorites/#{track.id}")
import soundcloud # create a client object with access token client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN') # Fetch a track by it's ID track = client.get('/tracks/290') # Like the track client.put('/me/favorites/%d' % track.id)
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID', redirect_uri: 'https://example.com/callback' }); SC.connect().then(function() { // favorite the track with id 290 SC.put('/me/favorites/290'); }); </script>
See also:
- /me endpoint reference documentation.
Search
This section presumes you have:
Resources such as sounds, users, sets can be searched
using our API. Most endpoints will accept a q
param which you can
use to specify a keyword to search for in fields like title
,
username
, description
, etc. depending on the resource type.
Some resource types, such as sounds, can be filtered by fields like
license
, duration
or tag_list
.
require 'soundcloud' # create a client object with your app credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID') # find all sounds of buskers licensed under 'creative commons share alike' tracks = client.get('/tracks', :q => 'buskers', :licence => 'cc-by-sa')
import soundcloud # create a client object with your app credentials client = soundcloud.Client(client_id='YOUR_CLIENT_ID') # find all sounds of buskers licensed under 'creative commons share alike' tracks = client.get('/tracks', q='buskers', license='cc-by-sa')
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID' }); // find all sounds of buskers licensed under 'creative commons share alike' SC.get('/tracks', { q: 'buskers', license: 'cc-by-sa' }).then(function(tracks) { console.log(tracks); }); </script>
You can also specify ranges for bpm
, duration
, and more.
require 'soundcloud' # create a client object with your app credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID') # find all tracks with the genre 'punk' that have a tempo greater than 120 bpm. tracks = client.get('/tracks', :genres => 'punk', :bpm => { :from => 120 })
import soundcloud # create a client object with your app credentials client = soundcloud.Client(client_id='YOUR_CLIENT_ID') # find all tracks with the genre 'punk' that have a tempo greater than 120 bpm. tracks = client.get('/tracks', genres='punk', bpm={ 'from': 120 })
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID' }); // find all tracks with the genre 'punk' that have a tempo greater than 120 bpm. SC.get('/tracks', { genres: 'punk', bpm: { from: 120 } }).then(function(tracks) { console.log(tracks); }); </script>
For a complete list of search fields and filters, please see the API Reference for the resource type you'd like to search.
Pagination
This section presumes you have:
Most results from our API are returned as a collection. The number
of items in the collection returned is limited to 50 by
default with a maximum value of 200. Most endpoints support a
linked_partitioning
parameter that will allow you to page
through collections. When this parameter is passed, the response will
contain a next_href
property if there are additional results.
To fetch the next page of results, simply follow that URI. If the response
does not contain a next_href
property, you have reached the
end of the results.
require 'soundcloud' # create a client object with your app credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID') page_size = 100 # get first 100 tracks tracks = client.get('/tracks', :order => 'created_at', :limit => page_size) tracks.each { |t| puts t.title } # start paging through results, 100 at a time tracks = client.get('/tracks', :order => 'created_at', :limit => page_size, :linked_partitioning => 1) tracks.each { |t| puts t.title }
import soundcloud # create a client object with your app credentials client = soundcloud.Client(client_id='YOUR_CLIENT_ID') page_size = 100 # get first 100 tracks tracks = client.get('/tracks', order='created_at', limit=page_size) for track in tracks: print track.title # start paging through results, 100 at a time tracks = client.get('/tracks', order='created_at', limit=page_size, linked_partitioning=1) for track in tracks: print track.title
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID' }); var page_size = 100; SC.get('/tracks', { limit: page_size }).then(function(tracks) { // first 100 tracks }); SC.get('/tracks', { limit: page_size, linked_partitioning: 1 }).then(function(tracks) { // page through results, 100 at a time }); </script>
SoundCloud URLs
This section presumes you have:
If you have a permalink URL to a particular resource, but need more information such as an ID or other property. In these cases, you can use the /resolve endpoint to extract a full representation of the resource.
require 'soundcloud' # create client with your app's credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID') # a permalink to a track track_url = 'https://soundcloud.com/forss/voca-nomen-tuum' # resolve track URL into track resource track = client.get('/resolve', :url => track_url) # now that we have the track id, we can get a list of comments, for example client.get("/tracks/#{track.id}/comments").each do |comment| puts "Someone said: #{comment.body} at #{comment.timestamp}" end
import soundcloud # create client with access token client = soundcloud.Client(client_id='YOUR_CLIENT_ID') # a permalink to a track track_url = 'https://soundcloud.com/forss/voca-nomen-tuum' # resolve track URL into track resource track = client.get('/resolve', url=track_url) # now that we have the track id, we can get a list of comments, for example for track in client.get('/tracks/%d/comments' % track.id): print 'Someone said: %s at %d' % (comment.body, comment.timestamp)
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID' }); // permalink to a track var track_url = 'https://soundcloud.com/forss/voca-nomen-tuum'; var getComments = function (track) { return SC.get('/tracks/' + track.id + '/comments'); }; var listComments = function (comments) { comments.forEach(function(comment){ console.log(comment.body); }); }; SC.resolve(track_url).then(getComments).then(listComments); </script>
See also:
- /resolve endpoint reference documentation.
Cross Domain Requests
This section presumes you have:
Our API supports CORS for making cross domain requests. This means you can access SoundCloud API endpoints from JavaScript running in the browser. By requesting results formatted as JSON, you will be able to parse and use the response immediately.
<script src="http://code.jquery.com/jquery-1.7.2.js"></script>
<script>
var url = 'https://api.soundcloud.com/tracks?client_id=YOUR_CLIENT_ID';
$.getJSON(url, function(tracks) {
$(tracks).each(function(track) {
console.log(track.title);
}
});
</script>
We also support JSONP, which can be used by passing a callback
parameter in the query string of the URL you are requesting.
<script>
var processTracks = function(tracks) {
for (var i = 0; i < tracks.length; i++) {
console.log(track.title);
}
};
</script>
<script src="https://api.soundcloud.com/tracks?client_id=YOUR_CLIENT_ID&callback=processTracks"></script>
Errors
This section presumes you have:
When an error occurs, our API will return an appropriate HTTP status code and an error message description. Our SDKs will wrap this in an exception that you can catch and choose how to handle.
In this section:
require 'soundcloud' # create a client object with your app credentials client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID') # try to get a track begin track = client.get('/tracks/1') rescue Soundcloud::ResponseError => e puts "Error: #{e.message}, Status Code: #{e.response.code}" end
import soundcloud # create a client object with your app credentials client = soundcloud.Client(client_id='YOUR_CLIENT_ID') # try to get a track try: track = client.get('/tracks/1') except Exception, e: print 'Error: %s, Status Code: %d' % (e.message, e.response.status_code)
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script> <script> SC.initialize({ client_id: 'YOUR_CLIENT_ID' }); // all SDK methods return promises that pass errors to catch listeners SC.get('/tracks/1').catch(function(error) { alert('Error: ' + error.message); }); </script>
HTTP Status Codes
The response from SoundCloud will have an HTTP status code that will help you determine the cause of the error. Our API tries to use the appropriate HTTP status code to indicate the type of problem encountered.
Below is an overview of what those codes mean, along with some suggestions that might help you fix things.
400 Bad Request
This is likely to be caused by a programming error on your part. Check the requirements of the endpoint you're calling in the HTTP API Reference.
401 Unauthorized
This means that we were not able to authenticate you based on the information provided in the request. Make sure you're sending a client_id
or an access_token
.
Our public endpoints will work by just providing a client_id
. Acting on behalf of another user is different. The Authentication section gives a detailed explanation of how this works.
If you're connecting using OAuth, don't forget that tokens can expire. These will need to be refreshed. Not doing so can also result in getting a 401 error.
If you need to check your application's details, use the Your Applications page. This will include the client_id
for your application.
403 Forbidden
You don't have access to whatever it is you're asking for.
404 Not Found
You're asking for something that doesn't exist. Check the URL that you're requesting.
406 Not Accessible
This means it wasn't possible to respond with the format you requested. Check the Accept
header that you're sending.
422 Unprocessable Entity
The request was valid, but one or more of the parameters looks a little screwy. It's possible that you sent data in the wrong format. One example would be providing an array when we expected a string.
429 Too Many Requests
To keep the amount of spam on SoundCloud as low as possible, our API limits the rate at which you can perform certain actions. Read the Rate Limits page to find out more.
500 Internal Server Error
Uh-oh. Something went wrong on our side. We're sorry. We keep track of these, and we'll try to fix it!
503 Service Unavailable
This means that we're having some trouble, and our servers are too busy to handle your request. You'll want to check for these and give your user a chance to retry the request. We keep track of these and try to make sure they don't happen.
504 Gateway Timeout
This means the request is taking too long. However, it doesn't always mean that we didn't receive your request. We could still be chugging away on the changes you made, and this means that you may want to check before retrying.