Object Hierarchy

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
  • Advertisers
  • Campaigns
  • Ad Sets (formerly known as “Flights”)
  • Ads (formerly known as “Creatives”)
  • Assets

"Ad Studio Platform Structure"

Ad Accounts

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.

Advertisers

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.

Campaigns

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.

Ad Sets

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.

Ads

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.

Assets

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]

Overview

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

Eligibility Criteria

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
Advertiser entity no yes
Organization entity no yes
Podcasts placements yes no
Audio asset/voiceover automation yes no
Ad rotation yes no
Interests targeting yes no
Language targeting 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]

Overview

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.

Eligibility Criteria

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 COMPLETION_RATE field in the API differs from “Completion Rate” in the UI, see below for details)
Video Completion Rate Not available Referred to as COMPLETION_RATE. Represents the percentage of video ads that played all the way through to completion. Available for AU only.
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 SPEND field is not capped based on budget set by advertiser - in the event of overdelivery, SPEND may exceed the budget amount set by the advertiser but advertisers will only be billed up to their budget amount

Audiences [Alpha]

Overview

The Audiences API allows advertisers to create custom audiences from their first-party data. Currently only targeting is supported (no suppression).

Eligibility Criteria

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.

Metrics Glossary

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.

Metric/Field Definition
Ads Served ("SERVES") The total number of ads served (#)
Amount Spent ("SPEND") The total amount spent in this campaign, represented in micros – i.e., multiplied by 10 to the power of 6 (#)
Clicks ("CLICKS") The number of impressions in which your ad was clicked (#)
Click Through Rate (“CTR”) The percentage of ads that were clicked (%)
Completes (“COMPLETES”) The number of ads served that was played to the end (#)
Completion Rates (“COMPLETION_RATE”) The percentage of ads served that were played to the end (%) – NOTE: Applies to CPCL campaigns only
Errors (“ERRORS”) The number of times an error occurred (#)
Fetches(“FETCHES”) The number of times an ad is called from the ad server (#)
Frequency of Ads Served(“SERVE_FREQ”) The average number of times each person heard or viewed your ad (#)
Frequency of Paid Listens (“PAID_LISTEN_FREQ”) The average frequency for listens on a CPCL campaign – NOTE: Applies to CPCL campaigns only
Impressions("IMPRESSIONS") 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
Midpoints (“MIDPOINTS”) The number of users for which the ad played to the midpoint of the ads total length (#)
Paid Listens (“PAID_LISTENS”) The number of listens for a CPCL campaign where a user did NOT skip the ad – NOTE: Applies to CPCL campaigns only
Quartiles (“FIRST_QUARTILES”,“THIRD_QUARTILES”) The percentage of users who listened or viewed a given percentage of the ad (%)
Reach of Ads Served (“SERVE_REACH”) The number of unique users who received your ad (#)
Reach of Fetched Ads (“FETCH_REACH”) The number of unique users with FETCH events (#)
Reach of Paid Listens (“PAID_LISTEN_REACH”) The number of unique users who who had a paid listen for this CPCL campaign – NOTE: Applies to CPCL campaigns only
Render Ratio (“RENDER_RATIO”) The percentage of impressions in which a creative is actually displayed to the user (#)
Starts (“STARTS”) The number of times a user starts hearing/viewing your ad (#)
Skips("SKIPS") 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.

Metric/Field Definition
Conversion Rate (“CONVERSION_RATE”) The percentage of users who listened to the artist after seeing or hearing an ad served by the campaign (%)
Intent Rate (“INTENT_RATE”) The rate at which listeners indicated an intent to stream the artist again in the future (%)
New Listeners (“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 (#)
New Listener Streams ("NEW_LISTENER_STREAMS") Not available, do not use
New Listeners Conversion Rate (“NEW_LISTENER_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 (%)
Streams ("STREAMS") Not available, do not use
Streams per Listener (“STREAMS_PER_USER”) The average number of times each listener streamed the artist after seeing/hearing the ad (#)
Streams per New Listener (“STREAMS_PER_NEW_LISTENER”) The average number of times each new listener streamed the artist after seeing/hearing the ad (#)
Unique Listeners(“LISTENERS”) The number of users who listened to the artist after hearing/seeing an ad (#)