Ads API
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
Next steps
If you're not sure what to do now, try these recommendations:
-
New to the Ads API? See the Quick Start 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-support@spotify.com.
Subscribe to Newsletter
Sign up for our monthly Ads API newsletter here if you want to receive updates about new releases, test opportunities, and more!
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 most recent version of the Ads API is v1.4.
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
- Modification of response object
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 | Deprecation Date |
---|---|---|
v1.4 | November 2022 | TBA |
v1.3 | July 2022 | TBA |
v1.2 | December 2021 | August 25, 2022 |
v1.1 | June 2019 | August 25, 2022 |
v1.0 | March 2019 | July 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.4/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.4/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.
Release Notes
This section documents changes made to the Spotify Ads API.
November 2022
Announcing Ads API v1.4
All of the following updates are included under a new minor version (v1.4) released on November 29, 2022.
What's New
- [BETA - UK & CA ONLY] Introducing new Click objective with accompanying Call-to-Action (“CTA”) card format
- Spotify Ad Studio advertisers are now able to set up a click optimization goal for their campaigns along with reach and impressions goals introduced this year. Ads with click goal will be accompanied by a Call-to-Action card: a clickable ad experience consisting of an advertiser's companion image, a name and a call-to-action button. After the initial ad is served, the message will resurface across the Spotify app making it easier for listeners to remember and take action.
- New enum value
CLICKS
is available under thebid_optimization_goal
parameter when creating an ad set, updating an ad set, and retrieving bid/audience estimates - While in beta, click optimization + CTA cards are only available for:
- CA ad accounts targeting CA
- UK ad accounts targeting the UK
- CTA cards will be enabled for music ads only (not video) – create ad endpoint now includes:
- New required parameter
brand_name
: Displayed in ad - New optional parameter
tagline
: Displayed in CTA card, max 140 characters - These two parameters are included in the response when retrieving ads
- New required parameter
- Enforcing new validation logic, see Breaking Changes/Deprecations section below for details
Breaking Changes/Deprecations
- New parameter
brand_name
is now required when creating an ad - Removed and replaced
slot_type
withformat
under ad sets/estimates targeting object - Removed
country_codes
(array of string) under ad sets/estimatestargeting
object and replaced withcountry_code
(string) - Validation rules added:
- Ad set start and end dates must be in the future
- Max ad set duration of 365 days
- Minimum length of 2 characters and maximum of 120 characters for campaigns, ad sets and ads entity names
- Only one country may be targeted per ad set
August 2022
All of the following updates are included under the current version of the API v1.3:
- New enum value
ARTIST_CONTENT
is available under theartist_promotion_goal
parameter when creating an ad set or updating an ad set: Users can now specify when they are promoting an artist's merch or concert by selecting this option (NOTE:ARTIST_BOOST
should continue to be used when promoting an artist's music on Spotify).
July 2022 - v1.3
Announcing Ads API v1.3
All of the following updates are included under a new minor version (v1.3) released July 2022.
What's New
- New minor version v1.3 released. Note: v1.1 and v1.2 will be fully deprecated on August 25, 2022. See Versioning section for version schedules.
- Addition of effective cost per mille and completed listen fields,
ECPM
andECPCL
, to reporting endpoints. See Metrics Glossary for detailed definitions. - Ad sets and Estimates requests have been updated to use an auction pricing model, see "Breaking Changes/Deprecations" below for details
frequency_caps
is no longer a required parameter for create ad sets requests; it is now optional. Iffrequency_caps
is not specified, API will default to the maximum allowed values:- 5 per day
- 35 per week
- 50 per month
Breaking Changes/Deprecations
- Addition of
bid_optimization_goal
,bid_strategy
, andbid_micro_amount
to ad sets output responses, as required fields to create ad sets requests, and as optional fields to update ad sets requests- Allowed values for
bid_optimization_goal
are:EVEN_IMPRESSION_DELIVERY
: We’ll aim to deliver as many impressions as possible to your target audience. Not available for active audio (CPCL) ad sets.REACH
: We’ll aim to reach as many unique listeners as possible with your message.AD_COMPLETES
: We’ll aim to deliver as many impressions as possible to your target audience. Available for active audio (CPCL) ad sets only.
- Allowed values for
bid_strategy
are:MAX_BID
: The bid you specify will act as a ceiling/cap.
- Allowed values for
- The following fields under the ad sets objects have been renamed:
optimization
is nowartist_promotion
optimization_goal
is nowartist_promotion_goal
optimization_target
is nowartist_promotion_target
optimization_target_type
is nowartist_promotion_target_type
- The previous
/estimate
endpoints are deprecated and replaced with two new ones (Get Bid Estimate and Get Audience Estimate) that allow users to specify bid details:POST /v1.3/adAccounts/{ad_account_id}/estimate/audience
is replacingPOST /v1.2/estimate
POST /v1.3/adAccounts/{ad_account_id}/estimate/bid
is replacingPOST /v1.2/adAccounts/{ad_account_id}/estimate/cost
Documentation Updates
- Migrated documentation to main portal Spotify for Developers
December 2021 - v1.2
Announcing Ads API v1.2
All of the following updates are included under a new minor version (v1.2) released December 2021.
What's New
- New minor version v1.2 released
- Added new pricing estimate endpoint to estimate your CPM/CLCL/CPCV based on specified targeting parameters
POST /adAccounts/{ad_account_id}/estimate/cost
- Added
custom_audience_ids
under thetargeting
parameter for ad sets- You now have the option to specify custom audiences to target when creating/updating an ad set
- Added
third_party_viewability_tracking
for ads- You now have the ability to set up third-party viewability tracking when creating/updating an ad
- NOTE: This is currently only supported for measurement partner
IAS
Breaking Changes/Deprecations
- “Flights” have been renamed “Ad Sets”
- We have renamed all instances of these entities in v1.2 in order to match the nomenclature used in the Ad Studio UI
- “Creatives” have been renamed “Ads”
- We have renamed all instances of these entities in v1.2 in order to match the nomenclature used in the Ad Studio UI
- Removed parameter “unit_cost_micro_amount” from Create Ad Set and Update Ad Set (fka Flight) endpoints
Documentation Updates
- Added new sections: “Metrics Glossary” and “Release Notes”
- Added additional detail on the expected behavior of the
report_datetime_range
filter under the Reporting API - Updates to “Versioning” section - added version release/sunset schedule
November 2021 - v1.1
- Added support for podcast ad performance data to the Reporting API
- Ads served to podcast listeners on Spotify will automatically be reflected without making any updates to your integration
- To capture the impressions served off Spotify, you will need to update your integration by adding the new metric called
OFF_SPOTIFY_IMPRESSIONS
- There are no breaking changes associated with this launch, however, we recommend that you complete this update as soon as possible in order to accurately reflect podcast ad performance
June 2019 - v1.1
Announcing Ads API v1.1
v1.1 was released June 2019
What's New
- Combined the
/geo
and/geos
endpoints into just/geos
. See docs here /geos
endpoint now allows you to specify a type of geo you are searching for as a filter in a query param.
April 2019 - v1.0
- Renamed the landing_page_url field to be landing_page_domain so it is consistent across the API
- Renamed arrays on GET targets and GET campaigns to be consistent with rest of API
- Refactored statuses on flight endpoint
- Pausing status for flight and flight links
- Previously, you had to pause a flight on the update flight request. Now, there is a separate endpoint to pause / activate / archive a flight. You are no longer able to change the status on the update flight request.
- Added Flight Links endpoints
- Flight links are a connection between flights and creatives that ensure the creative(s) and its contents are compatible with the flight’s targeting
- Added serving status endpoint
- The new serving status endpoint indicates whether your flight is serving or not
March 2019 - v1.0
- Added Campaign Status Endpoint
- The available statuses for campaigns are ACTIVE, PAUSED, and ARCHIVED
- Removed CANCELLED as a status on campaigns
- Campaigns can now only be archived, not cancelled
- Archiving will permanently pause a campaign, you cannot unarchive a campaign
- Archiving a campaign will prevent delivery across all associated flights
- Removed ability to update campaign status on PUT
- Use the campaign status endpoint
- Added support for slicing on all GET LIST requests for creatives, flights, and campaigns
- Slicing is the ability to specify what fields you want returned
- How it works: GET LIST endpoints, there is a query parameter called
fields
where you can specify a comma-separated list of fields you want returned
- Added support for filtering on all the GET LIST requests for creatives, flights, and campaigns
- Filtering is the ability to filter your results based on specific criteria (e.g., Get Flights for a specific Advertiser ID)
- How it works: On the GET LIST endpoints, there are optional query parameters to specify the filter
- Added support for ordering by a specific field on GET LIST requests for creatives, campaigns, and flights
- How it works: There are optional query parameters to specify the ordering field, ascending or descending based on the field