Your Ad Studio account comprises sets of related objects organized in a hierarchy. The Ads API gives you direct, programmatic access to these objects. From top to bottom, the objects that build the structure of your account include:
- Ad Accounts
- Ad Sets (formerly known as “Flights”)
- Ads (formerly known as “Creatives”)
You must have an ad account before you can create advertisers, campaigns, ad sets, or ads. For more information about creating an ad account, see Getting Started.
Use the List Ad Accounts endpoint to view information about your account after it has been set up.
An advertiser is an object that is associated with one or more campaigns. You should create an advertiser after your account is activated. Use the Create Advertiser endpoint to add an advertiser to your account.
A campaign is an object that contains and organizes one or more ad sets. Also, you need a campaign before you can create an ad set. Use the Create Campaign endpoint to ad a campaign to your account.
An ad set is the core component of your Ad Studio advertising campaign. It is a child of a campaign object and contains all the essential information Ad Studio needs to execute your campaign. For example, an ad set contains:
- Information about how, when, and where your campaign runs (e.g., start and end dates, budgets, targeting, etc).
- One or more ads. And, a single ad can be used across multiple ad sets.
See the Create Ad Set endpoint for more information or to add an ad set to a campaign.
An ad is an object that contains an image asset along with either an audio or video asset. These assets are required to create an ad. See the eponymous Create Ad endpoint to get started.
The Ad Studio platform supports audio, video, and image assets. These assets are required to create an ad. The asset endpoints help you upload and manage these items. See the following endpoints for more information:
Campaign Management [Closed Beta]
The Campaign Management API allows you to create and manage campaigns, ad sets, and ads at scale. It also includes endpoints to estimate audience size and CPM based on your targeting specifications (set at the ad set level).
Currently, the Campaign Management API is in closed beta and requires an allowlisting process to gain access. If you are interested in participating in the beta program, please fill in the pre-integration questionnaire here and the Spotify Ads API team will review your request within 3-5 business days.
Please note that the Campaign Management API is only available for advertisers with a Spotify Ad Studio account.
Differences from the UI
|Feature||Supported in Spotify Ad Studio UI||Supported in Spotify Ads API|
|Audio asset/voiceover automation||yes||no|
|Zip code targeting||yes||no|
|Real-time context targeting||yes||yes - Referred to as playlist targeting|
|Fan targeting||yes||yes - Referred to as artist targeting|
|MOAT viewability tracking set up||yes||no - Only IAS is available|
|DCM impression and click tracking set up||yes||no|
|Call-to-action button customization||yes||no - The button for ads created via API will default to “Learn More”|
Reporting [Open Beta]
The Reporting API allows advertisers to access real-time performance data for campaigns created via Ad Studio UI or via third party platforms integrated with Spotify Campaign Management API based on custom queries. You can find definitions of the available metrics (aka “fields”) in the Metrics Glossary section.
Filters allow you to specify criteria for the data that will be returned, while dimensions allow you to specify how the returned data will be partitioned.
As of March 2022, the Reporting API is in open beta and no longer requires a manual allowlisting process to gain access. As soon as you have set up your application, your client ID will be able to access these endpoints automatically.
Please note that the Reporting API is only available for advertisers with a Spotify Ad Studio account.
Differences from the UI
|Metric||Spotify Ad Studio UI||Spotify Ads API|
|Audio Completion Rate||Referred to as “Completion Rate”. Represents the percentage of audio ads played to completion. Only for ads placed in music.||This metric is not available directly but can be calculated by dividing COMPLETES / SERVES (NOTE: The
|Video Completion Rate||Not available||Referred to as
|Budgets and Spend||“Budget Spent” metric (available at the ad set level only) will never exceed the budget amount set by the advertiser – overdelivery is only reflected in the ‘Pacing’ column||
The Audiences API allows advertisers to create custom audiences from their first-party data. Currently only targeting is supported (no suppression).
Currently, the Audiences API is in alpha and requires an allowlisting process to gain access. If you are interested in participating in the alpha program, please fill in the pre-integration questionnaire here and the Spotify Ads API team will review your request within 3-5 business days.
Please note that the Audiences API is only available for advertisers with a Spotify Ad Studio account. During alpha testing, market availability for the Audiences API will be limited to the US, UK, CA, and AU.
This section includes definitions for all of the campaign metrics (referred to as
fields) that are available via the Reporting API.
Campaign Performance Metrics
These metrics provide the information you need to manage and optimize your campaigns efficiently and in real-time.
|Ads Served (
||The total number of ads served (#)|
|Amount Spent (
||The total amount spent in this campaign, represented in micros – i.e., multiplied by 10 to the power of 6 (#)|
||The number of impressions in which your ad was clicked (#)|
|Click Through Rate (
||The percentage of ads that were clicked (%)|
||The number of ads served that was played to the end (#)|
|Completion Rates (
||The percentage of ads served that were played to the end (%) – NOTE: Applies to CPCL campaigns only|
||The number of times an error occurred (#)|
||The number of times an ad is called from the ad server (#)|
|Frequency of Ads Served(
||The average number of times each person heard or viewed your ad (#)|
|Frequency of Paid Listens (
||The average frequency for listens on a CPCL campaign – NOTE: Applies to CPCL campaigns only|
||The number of times an ad has been successfully served (#) – NOTE: The API reports on exact impressions, whereas the UI only reports impressions delivered within budgets|
||The number of users for which the ad played to the midpoint of the ads total length (#)|
|Paid Listens (
||The number of listens for a CPCL campaign where a user did NOT skip the ad – NOTE: Applies to CPCL campaigns only|
||The percentage of users who listened or viewed a given percentage of the ad (%)|
|Reach of Ads Served (
||The number of unique users who received your ad (#)|
|Reach of Fetched Ads (
||The number of unique users with FETCH events (#)|
|Reach of Paid Listens (
||The number of unique users who who had a paid listen for this CPCL campaign – NOTE: Applies to CPCL campaigns only|
|Render Ratio (
||The percentage of impressions in which a creative is actually displayed to the user (#)|
||The number of times a user starts hearing/viewing your ad (#)|
||The number of times a user skips an ad – NOTE: Skippable ads are currently supported in AU only (#)|
Streaming Conversion Metrics
Available only for music promotion campaigns. These metrics show you how listeners are responding to your ad so that you can understand how advertising impacts the listener journey on Spotify.
|Conversion Rate (
||The percentage of users who listened to the artist after seeing or hearing an ad served by the campaign (%)|
|Intent Rate (
||The rate at which listeners indicated an intent to stream the artist again in the future (%)|
|New Listeners (
||The total number of users who listened to the artist for the first time in at least a month after seeing or hearing the ad (#)|
||Not available, do not use|
|New Listeners Conversion Rate (
||The percentage of users who listened to the artist for the first time in at least a month after seeing or hearing the ad (%)|
||Not available, do not use|
|Streams per Listener (
||The average number of times each listener streamed the artist after seeing/hearing the ad (#)|
|Streams per New Listener (
||The average number of times each new listener streamed the artist after seeing/hearing the ad (#)|
||The number of users who listened to the artist after hearing/seeing an ad (#)|