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

Release Notes

This section documents changes made to the Spotify Ads API.

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

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

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