Ads API

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

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.

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

Sign up for our monthly Ads API newsletter here if you want to receive updates about new releases, test opportunities, and more!

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.

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)

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.

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.

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. 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.

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

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.

This section documents changes made to the Spotify Ads API.

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 the bid_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
  • 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 with format under ad sets/estimates targeting object
• Removed country_codes (array of string) under ad sets/estimates targeting object and replaced with country_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

All of the following updates are included under the current version of the API v1.3:

• New enum value ARTIST_CONTENT is available under the artist_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).

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 and ECPCL, 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. If frequency_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, and bid_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.
• The following fields under the ad sets objects have been renamed:
  • optimization is now artist_promotion
  • optimization_goal is now artist_promotion_goal
  • optimization_target is now artist_promotion_target
  • optimization_target_type is now artist_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 replacing POST /v1.2/estimate
  • POST /v1.3/adAccounts/{ad_account_id}/estimate/bid is replacing POST /v1.2/adAccounts/{ad_account_id}/estimate/cost

Documentation Updates

• Migrated documentation to main portal Spotify for Developers

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 the targeting 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

• 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

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.

• 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

• 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