Ads API Beta

About

The Spotify Ads API lets you build, manage, and report on Ad Studio campaigns. This guide can help you get started. Topics include:

  • Getting started requirements and instructions
  • An Ad Studio overview
  • Descriptions of available endpoints
  • Help and support information

Note: Currently, Campaign Management and Audiences capabilities are in closed testing and require an allowlisting process to gain access. If you are interested in using these endpoints, please fill in the pre-integration questionnaire here and the Spotify Ads API team will review your request within 3-5 business days. Reporting capabilities are in open beta and do not require any allowlisting.

Next steps

If you’re not sure what to do now, try these recommendations:

  • New to the Ads API? See the Getting Started section. It provides instructions about how to set up an account to work with our API.

  • Already using the Ads API? Great! Check the Release Notes section for information on the latest changes, or browse the available methods below.

Support

To report a bug or ask questions about this service, contact the Ads API team at ads-api-solutions@spotify.com.

API Design

This section covers important design elements that affect how the Ads API works. Take a moment to review this information.

Rate Limiting

Rate limiting caps the number of API calls a user or app can make within a set period of time. The Ads API applies RPS rate limits on a per app basis for each client ID, regardless of the number of simultaneous app users. These limits help Spotify provide API access equitably to all our engineering partners.

Note: If our API returns status code 429, it means that you have sent too many requests. When this happens, check the Retry-After header, where you will see a number displayed. This is the number of seconds that you need to wait before you try your request again.

Rate Limit On Rate Limit Request Window (seconds) Sustained Requests per second (RPS) limit
Client ID 1500 30s 50 RPS
IP 500 10s 50 RPS

We have two types of rate limits per partner for production:

  • per partner integration 50 rps (calculated in 30 second window)
  • per IP 15 rps (calculated in 10 second window)

Versioning

The latest version of the Ads API is v1.2

We follow major.minor.patch schema. Endpoints will have major.minor only.

Patch updates will contain NON-breaking changes, and will not be included in the url path. This allows us to continuously deliver.

Minor version upgrades will happen if required in quarterly basis, and will include breaking changes if there are any. Breaking contract changes will first be introduced as “Deprecated” and will only be supported for one minor version.

Example: Let’s say we want to remove the statuses field from the Get Ad Sets payload and we are currently in v1.0. We will mark statuses field as deprecated in our documentation and in our generated client in v1.1. Then statuses field will be removed in v1.2.

Version Schedules

We strongly recommend that you use the newest available version when upgrading your integration.

API Version Release Date Sunset Date
v1.2 December 2021 TBD
v1.1 June 2019 TBD
v1.0 March 2019 April 1, 2022

Filtering and Querying

On all the GET LIST requests for ads, ad sets, and campaigns, we support the ability to filter on specific criteria.

Example: GET Ad Sets - filter by ad IDs or advertiser IDs.

On the GET LIST endpoints, there are optional query parameters to specify the filter.

For querying, you can search by name in a free form textfield. Name = (insert example). You can also query by status but it must be a preexisting status (ex. COMPLETED) and must be a comma separated list of statuses. All IDs must be existing IDs in UUID forms and must be exact (i.e., not contain a particular letter or number). IDs need to be a comma separated list.

Slicing

For all GET calls we support retrieving any top level field from the response object. In order to specify the fields you want returned, you pass a query parameter called fields. The fields query parameter is a comma separated list of the top level field names you want returned.

Example:

GET

https://api-partner.spotify.com/ads/v1.2/adAccounts/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/adSets?fields=id,status

Response

{"ad_sets":[{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","status":"COMPLETED"}],"total_ad_sets":7160}

ID and Status are requested in this example. If no fields are specified, all fields of the object will be returned.

Time Format

Times are always recorded in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.

Pagination

Some endpoints support a way of paging the dataset, taking an offset and page size as query parameters.

  • Page size specifies the number of results to be returned from the call. If not specified, the default page size value is 50. The max page size value is also 50.
  • Offset specifies where you want to start.

Example:

GET

https://api-partner.spotify.com/ads/v1.2/adAccounts/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/adSets?pageSize=5&offset=10

Response

{"ad_sets":[{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx"},{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}],"total_ad_sets":7160}

If you had a page size of 5, you’d get 5 results. On the next page you’d put an offset of 6 and get 6 through 10. We return the total number of entities, which is useful for displaying total page count so you can jump through pages.