Ads API Guides

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

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 Get Ad Accounts endpoint to view information about your account after it has been set up.

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 create a campaign under your ad 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, bids, budgets, targeting, etc).
• One or more ads.

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. Each ad be linked to an ad set but a given ad cannot be linked to multiple ad sets. 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. Use the following endpoints to first create and then upload an asset:

• Create Asset
• Upload Asset

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 bid amount based on your targeting specifications (set at the ad set level).

As of August 2023, the Campaign Management API is generally available ("GA") 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 Campaign Management API is only available for advertisers with a Spotify Ad Studio account.

Most features available in the Ad Studio UI are also available via the Ads API, with a few exceptions:

Follow these steps to build your first end-to-end campaign with the Ads API. NOTE: The below sample curl requests do not reflect every request parameter available.

If you're unsure of your ad account ID, you can call the Get Ad Accounts endpoint to return a list of all ad accounts available to the current authenticated user.

Upon success, the API will return an ID for the newly created campaign. Store this ID for use in Step 5 (Create an ad set).

Use the /targets endpoints to understand/retrieve the available targeting options -- supported categories include:

• artist
• genre
• playlist
• interest
• language
• geographic location (country, region, DMA, city, and postal code)

In order to help plan your campaign, we recommend using the /estimates endpoints to help forecast estimated audience size and recommended bid amount based on your targeting specifications (NOTE: Estimates are NOT a guarantee of performance).

Retrieve a recommended bid range:

Retrieve an audience estimate:

Upon success, the API will return an ID for the newly created ad set. Store this ID for use in Step 7 (Create an ad).

TIP: If you want to ensure your ad set is not trafficked while you are still finalizing details, you can set the "delivery" to "OFF" until you are ready to have it go live.

First, create an asset (the below example is for creating a companion image asset):

Upon success, the API will return an ID for the newly created image asset.

Next, send upload your file to the newly created asset:

TIP: You can confirm the asset has been processed successfully by calling the Get Asset endpoint and referring to 'status' in the response:

Repeat the above upload process for either an audio or a video asset and then proceed to Step 7.

All ads must include either an audio asset or a video asset, in addition to a companion image asset.

Upon success, the API will return an ID for the newly created ad.

TIP: If you want to ensure your ad is not trafficked while you are still finalizing details, you can set the "delivery" to "OFF" until you are ready to have it go live.

Congratulations on creating your first full campaign! Once your campaign has been approved through the review process and goes live, you can track its performance using the Get Aggregate Report by Ad Account Id endpoint.

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.

As of November 2022, the Reporting API is generally available ("GA") 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.

This section includes definitions for all of the campaign metrics (referred to as fields) that are available via the Reports endpoints.

These metrics provide the information you need to manage and optimize your campaigns efficiently and in real-time.

Available only for artist and podcast 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.