Ads API Beta
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.
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.
To report a bug or ask questions about this service, contact the Ads API team at firstname.lastname@example.org.
This section covers important design elements that affect how the Ads API works. Take a moment to review this information.
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|
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)
Our Ads API public endpoints use a
major.minor version in their URL path parameter, like
/v1.2/. New minor (e.g.
/v1.3/) and major (e.g.
/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:
- 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.
- 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.
- 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.
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.
We strongly recommend that you use the newest available version when upgrading your integration.
|API Version||Release Date||Sunset Date|
|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.
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 query parameter is a comma separated list of the top level field names you want returned.
Status are requested in this example. If no fields are specified, all fields of the object will be returned.
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.
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.