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

Our Ads API public endpoints use a major.minor version in their URL path parameter, like /v1.2/. New minor (e.g. /v1.2/ to /v1.3/) and major (e.g. /v1.n/ to /v2.n/) version API releases will include a URL path parameter update. The API team considers these releases (minor and major) breaking, as clients will need to update their calls to the new URL endpoints. In other words, clients will automatically get “patch” releases for free, but major and minor updates require an update.

Taking inspiration from best in class API examples like Stripe, here’s how the API team thinks about delineating what lands in specific versions:

Patch releases:

Addition of new optional request body parameters to existing API methods
Bug fixes that would not warrant a minor, or major release
Changing the order of properties in existing API responses
Documentation updates
Testing improvements (e.g. more validation, coverage, etc.)
Codebase improvements

Minor releases, e.g. /v1.2/ to /v1.3/:

Addition of new endpoints
Addition of new required request body parameters
Default value is changed
Deprecation of existing endpoints
Deprecation of existing request body parameters
Deprecation of URL path parameters

Major releases, e.g. /v1.2/ to /v2/:

Modifying pre-existing request body parameters
Modifying pre-existing URL path parameters
Removing pre-existing endpoints

For each of these new API version launches the API team will communicate with clients and detail the release notes in the API changelog.

Deprecation

If any API resource needs to be removed, first the API resource will be marked as deprecated. Then, the API team will release a future version of the API. After this release, the API team will communicate to our consumers and coordinate the future removal plans for the deprecated endpoints.

For example, let’s say we wanted to remove the statuses field from the v1.0 Get Ad Sets payload. statuses field would be marked 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.