Pagination Updates on Our API

As part of our efforts to improve our APIs, we’re introducing updates on how we paginate over tracks. This only affects developers and apps that aren’t strictly relying on the next_href field, but rather custom manipulating the offset to request a page.

Affected Endpoints

The following endpoints are affected:

• /users/:userId/tracks
• /me/tracks
• /users/:userId/playlists
• /me/playlists

Going forward, the paginated responses for the above endpoints will be represented via a cursor in the next_href field. The cursor field will replace the need for an offset to paginate, while also improving the performance of this endpoint. We recommend that developers strictly rely on the next_href field to request paginated results.

Current Format

Here’s the current format, which uses offset for next_href:

https://api.soundcloud.com/users/123/tracks?linked_partitioning=true&limit=1&offset=1

New Format

Here’s the new format, which uses cursor for next_href:

https://api.soundcloud.com/users/123/tracks?linked_partitioning=true&page_size=10&cursor=2018-02-27T14:37:10.000Z,tracks,00405959469

Example Response

Here’s an example response:

{
  "collection": [
    {
      //... track
    }
  ],
  "next_href": "https://api.soundcloud.com/users/123/tracks?linked_partitioning=true&page_size=10&cursor=2018-02-27T14:37:10.000Z,tracks,00405959469"
}

This change will be in effect by 28 September 2020.

A Quick Note about the linked_partitioning Field

Setting the linked_partitioning field to true is our recommended way of fetching paginating responses. The shape of the response is an object with a cursor and the collection of results, rather than an array of the collection. In the near future, all responses for a collection will be paginated by default and served as an object. We highly recommended that developers include this parameter in their requests, as it’s the only way the API can guarantee paginated responses.

To get information about future updates, please follow us on Twitter and subscribe to the Backstage Blog.