Ads API Guides

Your Ads Manager 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:

• Businesses
• Ad Accounts
• Campaigns
• Ad Sets
• Ads
• Assets

When you create an account in Spotify Ads Manager, a business account and an associated ad account will automatically be created for you. A business is an object used to centrally manage multiple ad accounts.

You must have an ad account before you can create advertisers, campaigns, ad sets, or ads. Use the Get Ad Account by ID 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 Ads Manager campaign. It is a child of a campaign object and contains all the essential information Ads Manager 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 must 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 Ads Manager 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 Ads Manager account.

Most features available in the Ads Manager 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 business ID, you can call the Get Businesses for Current User endpoint to return a list of all businesses available to the current authenticated user.

You can then use the business ID to retrieve a list of all ad accounts under the business that the current authenticated user has access to via the Get Ad Accounts for Current User by Business ID endpoint.

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)
• podcast episode topics
• sensitive topic targets

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, 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. There are endpoints available to do a chunked upload for larger audio or video files.

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

The Reporting API allows advertisers to access real-time performance data for campaigns created via Ads Manager 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 Ads Manager 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 campaigns using artist promotion or the streams objective. These metrics show you how listeners are responding to your ad so that you can understand how advertising impacts the listener journey on Spotify.

Description: We've updated our attribution methodology with improved data resolution, which helps us provide a deterministic understanding of the customers who take action after seeing or hearing an ad on Spotify. The following information is applicable to campaigns with a start date of Dec 3, 2024 or earlier. Learn more about the updated attribution methodology

Description: Legacy metrics are metrics that are being sunsetted or no longer supported by Spotify Ads Manager. They'll only be used for historical reporting purposes. All legacy metrics will be removed from v4 and no longer supported in the Ads API.

These metrics track the actions users take with your app after interacting with your ad, helping you to understand how your advertising influences behavior associated with your app.