Connect the world of sound

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, PHP, iOS and 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.

Authentication

This section presumes you have:

  1. Registered your App

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.

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="http://connect.soundcloud.com/sdk.js"></script>
<script>
// initialize client with app credentials
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'REDIRECT_URL'
});

// initiate auth popup
SC.connect(function() {
  SC.get('/me', 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

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 => 'REDIRECT_URL')

# 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='REDIRECT_URL')

# redirect user to authorize URL
redirect client.authorize_url()

<?php
require_once 'Services/Soundcloud.php';

// create client object with app credentials
$client = new Services_Soundcloud(
  'CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URL');

// redirect user to authorize URL
header("Location: " . $client->getAuthorizeUrl());

// 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.

SoundCloud Connect screen
Users of your app will be redirected to the SoundCloud Connect screen.

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 => 'REDIRECT_URL')

# 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='REDIRECT_URL')

# exchange authorization code for access token
code = params['code']
access_token = client.exchange_token(code)

<?php
require_once 'Services/Soundcloud.php';

// create client object with app credentials
$client = new Services_Soundcloud('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URL');

// exchange authorization code for access token
$code = $_GET['code'];
$access_token = $client->accessToken($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

<?php
require_once 'Services/Soundcloud.php';

// create client object and set access token
$client = new Services_Soundcloud('CLIENT_ID', 'CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// make an authenticated call
$current_user = json_decode($client->get('me'));
print $current_user->username;

// this example is not applicable to the JavaScript SDK

Refreshing Tokens

Unless you specifically request a non-expiring token, you will need to periodically refresh your access tokens.

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

<?php
 require_once 'Services/Soundcloud.php';

 // create client object and set access token
 $client = new Services_Soundcloud('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URL');
 $client->setAccessToken('YOUR_ACCESS_TOKEN');

 // refresh access token
 $token = $client->accessTokenRefresh('SOME_REFRESH_TOKEN');

// 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.

If you are building a Mobile or Desktop app, be sure to check out our Cocoa and Java SDKs as well as our Desktop and Mobile Sharing Kits.

When building apps for mobile devices, we recommend using our mobile optimized connect screen by setting display=popup in the authorization URL query string.

Mobile optimized connect screen
Mobile optimized connect screen.

You can also use our Sharing Kits for Windows, OS X, Android or iOS applications.

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

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// get the current user
$user = json_decode($client->get('me'));

// update the user's profile description
$user = json_decode($client->post('me', array(
   'description' => 'I am using the SoundCloud API!'
)));
print $user->description;

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

// update user's profile description
SC.connect(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 PHP SDK

// this example is not supported by the JavaScript SDK

Uploading Sounds

This section presumes you have:

  1. Registered your App
  2. Authenticated

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 a set or group. We support the following formats: AIFF, WAVE, FLAC, OGG, MP2, MP3, AAC, AMR and WMA.

If you are building a desktop or mobile application, we've simplified uploading with sharing kits for Windows, OS X, Android and iOS.

Uploading Audio Files

To upload a sound, send a POST request to the /tracks endpoint. This is done with one of our SDKs using the post method and passing information about the track being uploaded.

Tracks uploaded with 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

<?php
require_once 'Services/Soundcloud.php';

// create client object and set access token
$client = new Services_Soundcloud('CLIENT_ID', 'CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// upload audio file
$track = json_decode($client->post('tracks', array(
    'track[title]' => 'This is my sound',
    'track[asset_data]' => '@/absolute/path/to/file.mp3'
)));

// print track link
print $track->permalink_url;

// the JavaScript SDK does not by itself have access
// to the filesystem, so instead this example records
// some audio in the browser and uploads it.
SC.connect(function() {
  SC.record({
    start: function() {
      window.setTimeout(function() {
        SC.recordStop();
        SC.recordUpload({
          track: { title: 'This is my sound' }
        });
      }, 5000);
    }
  });
});

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:

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/13198684')

# 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/13198684')

# 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')
})

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// fetch a track by it's ID
$track = json_decode($client->get('tracks/13198684'));

// update the track's metadata
$client->put('tracks/' . $track->id, array(
  'track[description]' => 'This track was recorded in Berlin',
  'track[genre]' => 'Electronic',
  'track[artwork_data]' => '@/absolute/path/to/artwork.jpg'
));

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

// connect and update track data
SC.connect(function() {
  SC.get('/tracks/13198684', function(track) {
    SC.put(track.permalink_url, { 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"

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// get a list of connected social networks
$connections = json_decode($client->get('me/connections'));

// print out connection details
foreach ($connections as $connection) {
    print "Connection type: " . $connection->type . "\n";
    if ($connection->post_favorite)
        print "Favorites are posted to this network\n";
    if ($connection->post_publish)
        print "New sounds and sets are shared\n";
}

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

// list connected social networks
SC.connect(function() {
  SC.get('/me/connections', 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}]
})

<?php
require_once 'Services/Soundcloud.php';

// create client object and set access token
$client = new Services_Soundcloud('CLIENT_ID');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// get 'twitter' connection
$connection = array_pop(array_filter(json_decode(
     $client->get('me/connections')), function($c) {
        return $c->type == 'twitter';
}));

// upload audio file
$track = json_decode($client->post('tracks', array(
    'track[title]' => 'This is my sound',
    'track[asset_data]' => '@/absolute/path/to/file.mp3',
    'track[shared_to][][id]' => $connection->id
)));

// print track link
print $track->permalink_url;

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

SC.connect(function() {
  SC.record({
    start: function() {
      window.setTimeout(function() {
        SC.recordStop();
        SC.recordUpload({
          track: {
            title: 'This is my sound',
            connections: [ { id: 123 } ]  # id of connection
          }
        });
      }, 5000);
    }
  });
});
</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'
)

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// get 'twitter' connection
$connection = array_pop(array_filter(json_decode(
      $client->get('me/connections')), function($c) {
        return $c->type == 'twitter';
}));

// share sound on twitter
$client->post('/tracks/' . $track->id . '/shared-to/connections', array(
  'connections[][id]' => connection.id,
  'sharing-note' => 'Check out my new sound'
));

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

SC.connect(function() {
  SC.post('/tracks/123/shared-to/connections', {
    connections: [ { id: 456 } ],
    sharing-note: 'Check out my new sound'
  });
});
</script>

See also:

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 = [21778201, 22448500, 21928809].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), [21778201, 22448500, 21928809])

# create the playlist
client.post('/playlists', playlist={
    'title': 'My new album',
    'sharing': 'public',
    'tracks': tracks
})

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// create an array of track ids
$playlist  = 'playlist[title]=MyPlaylist&playlist[tracks][][id]=21778201';
$playlist .= '&playlist[tracks][][id]=22448500';

// create the playlist
$response = json_decode($client->post('playlists', $playlist));

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

SC.connect(function() {
  var tracks = [22448500, 21928809].map(function(id) { return { id: id } });
  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 = [21778201, 22448500, 21928809].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), [21778201, 22448500, 21928809])

# get playlist
playlist = client.get('/me/playlists')[0]

# add tracks to playlist
client.put(playlist.uri, playlist={
    'tracks': tracks
})

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// create an array of track ids
$tracks = array(21778201, 22448500, 21928809);

// get playlist
$playlist = array_pop(json_decode($client->get('me/playlists')));

// add tracks to playlist
$client->updatePlaylist($playlist->id, $tracks);

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

var tracks = [21778201, 22448500, 21928809];
SC.connect(function() {
  SC.get('/me/playlists', { limit: 1 }, function(playlist) {
    SC.put(playlist.uri, { playlist: { tracks: tracks } });
  });
});

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/1234323’)

# 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/1234323')

# list tracks in playlist
for track in playlist.tracks:
    print track['title']

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// get playlist
$playlist = json_decode($client->get('playlists/1234323'));

// list tracks in playlist
foreach ($playlist->tracks as $track) {
   print $track->title . "\n";
}

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

SC.get('/playlists/1234323', function(playlist) {
  for (var i = 0; i < playlist.tracks.length; i++) {
    console.log(playlist.tracks[i].length);
  }
});
</script>

See also:

Contributing a Sound to a Group

Groups are collections of users with something in common. Users can join groups that have shared interests, for instance a group of urban explorers mapping out the sounds of their respective cities, or a group of users using the same app. Your app can use our API to contribute sounds to a group that a user is a part of.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# get a specific track
track = client.get('/me/tracks').first

# get a group that the user has joined
group = client.get('/me/groups').first

# contribute track to group
group = client.post("/groups/#{group.id}/contributions", {
  :track => { :id => track.id }
})

import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# get a specific track
track = client.get('/me/tracks')[0]

# get a group that the user has joined
group = client.get('/me/groups')[0]

# contribute track to group
group = client.post('/groups/%d/contributions' % (group.id,), track={
    'id': track.id
})

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// get a specific track
$track = array_pop(json_decode($client->get('me/tracks')));

// get a group that the user has joined
$group = array_pop(json_decode($client->get('me/groups')));

// contribute track to group
$group = $client->post('groups/' . $group->id . '/contributions', array(
    'track[id]' => $track->id
));

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

SC.connect(function() {
  SC.get('/me/tracks', { limit: 1 }, function(tracks) {
    SC.get('/me/groups', { limit: 1 }, function(groups) {
      SC.post('/groups/' + groups[0].id + '/contributions', {
        track: { id: tracks[0].id }
      });
    });
  });
});
</script>

Similarly, you can also remove contributions.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# delete track id 59 from group id 123
client.delete('/groups/123/contributions/59')

import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# delete track id 59 from group id 123
client.delete('/groups/123/contributions/59')

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// delete track id 59 from group id 123
$client->delete('/groups/123/contributions/59');

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});
SC.connect(function() {
  SC.delete('/groups/123/contributions/59');
});
</script>

Playing Sounds

This section presumes you have:

  1. Registered your App

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.

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 = 'http://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 = 'http://soundcloud.com/forss/flickermood'
embed_info = client.get('/oembed', url=track_url)

# print the html for the player widget
print embed_info['html']

<?php
require_once 'Services/Soundcloud.php';

// create a client object with your app credentials
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setCurlOptions(array(CURLOPT_FOLLOWLOCATION => 1));

// get a tracks oembed data
$track_url = 'http://soundcloud.com/forss/flickermood';
$embed_info = json_decode($client->get('oembed', array('url' => $track_url)));

// render the html for the player widget
print $embed_info->html;

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

var track_url = 'http://soundcloud.com/forss/flickermood';
SC.oEmbed(track_url, { auto_play: true }, 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:

  1. Credit the uploader as the creator of the sound
  2. Credit SoundCloud as the source by including one of the logos found here
  3. Link to the SoundCloud URL containing the work
  4. 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

// this example is not supported by the PHP SDK

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

// stream track id 293
SC.stream("/tracks/293", function(sound){
  sound.play();
});
</script>

See also:

Comments

This section presumes you have:

  1. Registered your App
  2. Authenticated

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
})

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// get the latest track from authenticated user
$track = array_pop(json_decode($client->get('me/tracks', array('limit' => 1))));

// create a new timed comment
$comment = json_decode($client->post('tracks/' . $track->id . '/comments', array(
    'comment[body]' => 'This is a timed comment',
    'comment[timestamp]' => 1500
)));

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

SC.connect(function() {
  SC.get('/me/tracks', { limit: 1 }, function(tracks) {
    var track = tracks[0];
    SC.post('/tracks/' + track.id + '/comments', {
      comment: { body: 'This is a timed comment', timestamp: 1500 }
    });
  });
});
</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

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// get the latest track from authenticated user
$track = array_pop(json_decode($client->get('me/tracks', array('limit' => 1))));

// get a list of comments for the track
$comments = $client->get('/tracks/' . $track->id . '/comments');

// print out each comment
foreach ($comments as $comment)
    print $comment->body . "\n";

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

SC.connect(function() {
  SC.get('/me/tracks', { limit: 1 }, function(tracks) {
    SC.get('/tracks/' + tracks[0].id + '/comments', function(comments) {
      for (var i = 0; i < comments.length; i++)
        console.log(comments[0].body);
    });
  });
});
</script>

See also:

  • /tracks endpoint reference documentation.
  • /comments endpoint reference documentation.

Follow & Like

This section presumes you have:

  1. Registered your App
  2. Authenticated

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'

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');
$client->setAccessToken('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');
} catch (Services_Soundcloud_Invalid_Http_Response_Code_Exception $e) {
    if ($e->getHttpCode() == '404')
        print "You are not following user 3207\n";
}

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

SC.connect(function() {
  // Follow user with ID 3207
  SC.put('/me/followings/3207');

  // 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/43314655')

# 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/43314655')

# Like the track
client.put('/me/favorites/%d' % track.id)

<?php
require_once 'Services/Soundcloud.php';

// create a client object with access token
$client = new Services_Soundcloud('YOUR_CLIENT_ID');
$client->setAccessToken('YOUR_ACCESS_TOKEN');

// Fetch a track by it's ID
$track = json_decode($client->get('tracks/43314655'));

// Like the track
$client->put('me/favorites/' . $track->id);

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'YOUR_REDIRECT_URI'
});

SC.connect(function() {
  // favorite the track with id 43314655
  SC.put('/me/favorites/43314655');
});
</script>

See also:

This section presumes you have:

  1. Registered your App

Resources such as sounds, users, sets and groups 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')

<?php
require_once 'Services/Soundcloud.php';

// create a client object with your app credentials
$client = new Services_Soundcloud('YOUR_CLIENT_ID');

// find all sounds of buskers licensed under 'creative commons share alike'
$tracks = $client->get('tracks', array('q' => 'buskers', 'license' => 'cc-by-sa'));

<script src="http://connect.soundcloud.com/sdk.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' }, 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
})

<?php
require_once 'Services/Soundcloud.php';

// create a client object with your app credentials
$client = new Services_Soundcloud('YOUR_CLIENT_ID');

// find all tracks with the genre 'punk' that have a tempo greater than 120 bpm.
$tracks = $client->get('tracks', array('genres' => 'punk', 'bpm[from]' => 120));

<script src="http://connect.soundcloud.com/sdk.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 } }, 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:

  1. Registered your App

Most results from our API are returned as a collection. The number of items in the collection returned is limited to 50 by default. Most endpoints support limit and offset parameters that allow your app to page through collections. When you receive 0 items in a response, you can assume that you've reached the end of the collection. The maximum value is 200 for limit and 8000 for offset.

require 'soundcloud'

# create a client object with your app credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID')

page_size = 100

# get first page of tracks
tracks = client.get('/tracks', :order => 'created_at', :limit => page_size)
tracks.each { |t| puts t.title }

# get second page
tracks = client.get('/tracks', :order => 'created_at', :limit => page_size,
                    :offset => page_size)
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 page of tracks
tracks = client.get('/tracks', order='created_at', limit=page_size)
for track in tracks:
    print track.title

# get second page
tracks = client.get('/tracks', order='created_at', limit=page_size,
                    offset=page_size)
for track in tracks:
    print track.title

<?php
require_once 'Services/Soundcloud.php';

// create a client object with your app credentials
$client = new Services_Soundcloud('YOUR_CLIENT_ID');

$page_size = 100;

// get first page of tracks
$tracks = json_decode($client->get('tracks', array(
    'order' => 'created_at',
    'limit' => $page_size)
));

// get second page
$tracks = array_merge($tracks, json_decode($client->get('tracks', array(
    'order' => 'created_at',
    'limit' => $page_size,
    'offset' => $page_size
))));

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

var page_size = 200;

SC.get('/tracks', { limit: page_size }, function(tracks) {
  // first page of tracks
});

SC.get('/tracks', { limit: page_size, offset: page_size }, function(tracks) {
  // second page of tracks
});
</script>

SoundCloud URLs

This section presumes you have:

  1. Registered your App

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 = 'http://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 = 'http://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)

<?php
require_once 'Services/Soundcloud.php';

// create a client object with your app credentials
$client = new Services_Soundcloud('YOUR_CLIENT_ID');

// a permalink to a track
$track_url = 'http://soundcloud.com/forss/voca-nomen-tuum';

// resolve track URL into track resource
$track = json_decode($client->get('resolve', array('url' => $track_url)));

// now that we have the track id, we can get a list of comments, for example
foreach (json_decode($client->get('tracks/' . $track->id . 'comments')) as $c)
    print 'Someone said: ' . $c->body . ' at ' . $c->timestamp . "\n";

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

// permalink to a track
var track_url = 'http://soundcloud.com/forss/voca-nomen-tuum';

SC.get('/resolve', { url: track_url }, function(track) {
  SC.get('/tracks/' + track.id + '/comments', function(comments) {
    for (var i = 0; i < comments.length; i++) {
      console.log('Someone said: ' + comments[i].body);
    }
  });
});
</script>

See also:

  • /resolve endpoint reference documentation.

Cross Domain Requests

This section presumes you have:

  1. Registered your App

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.json?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.json?client_id=YOUR_CLIENT_ID&callback=processTracks"></script>

Errors

This section presumes you have:

  1. Registered your App

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/123')
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/123')
except Exception, e:
    print 'Error: %s, Status Code: %d' % (e.message, e.response.status_code)

<?php
require_once 'Services/Soundcloud.php';

// create a client object with your app credentials
$client = new Services_Soundcloud('YOUR_CLIENT_ID');

// try to get a track
try {
   $track = $client->get('tracks/123');
} catch (Services_Soundcloud_Invalid_Http_Response_Code_Exception $e) {
   print $e->getMessage();
}

<script src="http://connect.soundcloud.com/sdk.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

// all JavaScript SDK callback functions accept an 'error' param
SC.get('/tracks/1', function(track, error) {
  if (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.

400 Bad Request Probably caused by a programming error.
401 Unauthorized Make sure you're sending us a client_id or access_token.
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.
406 Not Accessible We found what you're looking for, but it can't be represented in the format you requested.
422 Unprocessable Entity The request looks alright, but one or more of the parameters looks a little screwy. It's possible that you sent data in the wrong format (e.g. an array where 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.
500 Internal Server Error Uh-oh. Something went wrong on our side. We're very sorry. We keep track of these and we'll try to fix it!
503 Service Unavailable Usually means 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. It doesn't necessarily mean that we didn't receive your request and aren't chugging away on the changes you made though, so you may want to check before retrying.