Skip to main content

Spotify Ads

Spotify Ads is Spotify's self-serve advertising platform for audio, video and podcast ads, managed in Spotify Ads Manager and through the Spotify Ads API. The Spotify Ads connector reads businesses, ad accounts, campaigns, ad sets, ads, assets, audiences, targeting options, estimates, datasets, pixels and performance reports, including CSV reports, and can create and update campaigns, ad sets, ads, drafts, audiences, members and measurement settings.

Spotify Ads icon

Power end-to-end data operations for your Spotify Ads API with Nexla. Our bi-directional Spotify Ads connector is purpose-built for Spotify Ads, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Spotify Ads or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Spotify Ads workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

  • Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
  • Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
  • API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
  • Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites​

Nexla connects to the Spotify Ads API (https://api-partner.spotify.com/ads/v3) as a Spotify user, through a Spotify developer app that you register. Complete the following steps before creating a credential in Nexla.

  1. Make sure you have a Spotify Ads Manager account with a business and at least one ad account in it. The Spotify user who authorizes Nexla must be a member of that business and ad account; Nexla can only read and change what that user can access.

  2. Sign in to the Spotify Developer Dashboard, and click Create app. Enter a name and description for the app.

  3. When asked which APIs the app uses, select Ads API.

  4. Add https://dataops.nexla.io/nexla-api/oauth/callback as a Redirect URI (or /nexla-api/oauth/callback on the Nexla host you sign in to). The redirect URI must match exactly.

  5. Save the app, then open its Settings page to copy the Client ID and reveal the Client Secret. Store the secret securely.

  6. Accept the Ads API Terms and Conditions for the app by visiting the Spotify Ads API Terms page and signing in with the app's Client ID. Until the terms are accepted, Spotify rejects requests with an error that the Client ID is not allow-listed. It can take up to an hour for the Client ID to be allow-listed after you accept.

Spotify requires an additional review before an app can use campaign management capabilities or onboard more than 25 users. Submit the pre-integration questionnaire or a quota extension request from the Developer Dashboard, and the Spotify Ads API team will follow up.

For complete details about app registration, authorization and the available endpoints, see the Spotify Ads API documentation.

Some destinations spend money or change live ads

The destination templates that create or update campaigns, ad sets and ads, and the template that publishes a draft campaign, act on live advertising. A live campaign, ad set or ad can start delivering and spending your ad account's budget as soon as it is created, published or turned on. These templates are marked Spends budget below. To prepare changes safely, use the draft templates, and send VALIDATE with Publish Campaign Draft before you publish.

Spotify Ads API rate limits

Spotify applies rate limits per Spotify user for each app: 1,500 requests per 30 seconds (50 per second) across the API. Reporting has stricter limits per app, shared by all of its users: 30 requests per 30 seconds for creating CSV reports, and 150 requests per 30 seconds for all other reporting endpoints. Spotify returns HTTP 429 Too Many Requests when a limit is exceeded. Templates that page through large result sets make one request per page.

Authenticate​

Credentials required​

An OAuth authentication flow where users must authorize an application to access their data

FieldRequiredSecretDescription
Authorization URLNoNoThe URL endpoint where users authenticate and authorize access
Client IDYesYesA unique public identifier assigned to your application
Access ScopeNoNoA space-separated list of permissions your application requests
Token URLNoNoThe URL endpoint where authorization codes are exchanged for access tokens
Client SecretYesYesA private key used to authenticate your application when requesting tokens

The OAuth 2.0 method is recommended. The Authorization URL and Token URL default to Spotify's endpoints (https://accounts.spotify.com/authorize/ and https://accounts.spotify.com/api/token); leave them unchanged. The Spotify Ads API does not use OAuth scopes, so leave Access Scope empty.

Create a credential in Nexla​

  1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

  2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

  3. Select the authentication method you want to use, and enter the required values:

    • OAuth 2.0: Enter the Client ID and Client Secret of your Spotify developer app. Spotify needs the Client Secret to issue tokens. Click the Authorize button, sign in to Spotify as the user that Nexla should act as, and approve access. Nexla stores the refresh token and gets new access tokens automatically.

    • Api Key: Enter a Spotify Ads API access token in the API Key Value field. Nexla sends it in the Authorization header as Bearer <token>. Spotify access tokens expire after one hour, so this method only suits short tasks, or setups where you refresh the token yourself and update the credential.

  4. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Nexla tests the credential by listing the Spotify ad categories.

Keep the Client Secret and any access tokens confidential. If a value is compromised, rotate the Client Secret in the Spotify Developer Dashboard, and update the credential.

Use as a data source​

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Spotify Ads connector tile, then select the credential that will be used to connect to Spotify Ads, and click Next; or, create a new Spotify Ads credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Spotify Ads endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below, grouped by area.

Spotify Ads objects are nested: a business holds ad accounts, and an ad account holds campaigns, ad sets, ads, assets and audiences. Most templates need a business ID or an ad account ID. Start with List Businesses, then List Business Ad Accounts, to find them, and use the matching list template to find any other ID a template asks for. Templates that say "Results are paged automatically" read every page; all other templates make a single request.

Businesses and members​

List Businesses

Lists the businesses that the authorized Spotify user belongs to, with each business's ID, name, type and status. Start here to find the business ID that the business-level templates need.

Get Business

Retrieves one business with its name, type and status.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the response fields.

List Business Members

Lists the members and invited users of a business, with each member's ID, role, email and assigned ad accounts.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Business Member

Retrieves one business member with their role, email, status and ad account invitations.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Member ID: the member_id value returned by the List Business Members template.
  • See the Spotify Ads API reference for the response fields.

List Member Ad Accounts

Lists the ad accounts in a business that one member belongs to.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Member ID: the member_id value returned by the List Business Members template.
  • See the Spotify Ads API reference for the response fields.

List Business Invitations

Lists the pending invitations to a business, with each invitation's ID, email, business role and ad account invitations.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the response fields.

Ad accounts​

List Business Ad Accounts

Lists the ad accounts in a business that the authorized user can access, with each account's ID, status, currency and your role on it. Use it to find the ad account ID that most other templates need.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Ad Account

Retrieves one ad account with its name, business, status, country, currency, industry, billing address and your role on it.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

List Ad Account Members

Lists the members of an ad account with each member's ID, role, name and email.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

List Change History

Lists the changes made in an ad account over the last 30 days: who changed what on campaigns, ad sets and creatives. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Experiment Availability

Shows which experiment types (CLS, SBL and A/B tests) the ad account can create, and the experiments that are active.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Campaigns​

List Campaigns

Lists an ad account's campaigns with each campaign's ID, name, objective, status, purchase order and dates. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Campaign

Retrieves one campaign with its name, objective, status and purchase order.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Campaign ID. Use the List Campaigns template to find it.
  • See the Spotify Ads API reference for the response fields.

List Campaign Drafts

Lists an ad account's draft campaigns, which are not delivered until they are published. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Campaign Draft

Retrieves one draft campaign.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Campaign ID. Use the List Campaign Drafts template to find it.
  • See the Spotify Ads API reference for the response fields.

Ad sets​

List Ad Sets

Lists an ad account's ad sets with each ad set's campaign, budget, bid, schedule, targeting and status. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

List Campaign Ad Sets

Lists the ad sets of one campaign with their budget, bid, schedule, targeting and status. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Campaign ID. Use the List Campaigns template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Ad Set

Retrieves one ad set with its schedule, budget, bid, targeting, delivery and status.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Ad Set ID. Use the List Ad Sets template to find it.
  • See the Spotify Ads API reference for the response fields.

List Ad Set Drafts

Lists an ad account's draft ad sets, which are not delivered until their campaign draft is published. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Ad Set Draft

Retrieves one draft ad set.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Ad Set ID. Use the List Ad Set Drafts template to find it.
  • See the Spotify Ads API reference for the response fields.

Ads​

List Ads

Lists an ad account's ads with each ad's ad set, status, delivery, schedule, assets, call to action and preview URL. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

List Ad Set Ads

Lists the ads of one ad set with their status, delivery, assets and call to action. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Ad Set ID. Use the List Ad Sets template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Ad

Retrieves one ad with its ad set, status, delivery, schedule, assets, call to action, tracking and preview URL. Any reject reasons are returned as a field of the ad.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Ad ID. Use the List Ads template to find it.
  • See the Spotify Ads API reference for the response fields.

List Ad Drafts

Lists an ad account's draft ads, which are not delivered until they are published. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Ad Draft

Retrieves one draft ad.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Ad ID. Use the List Ad Drafts template to find it.
  • See the Spotify Ads API reference for the response fields.

Assets​

List Assets

Lists an ad account's creative assets (audio, video and image), newest first, with each asset's type, status and URLs. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Asset

Retrieves the metadata of one creative asset: its type, status, duration and URL.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Asset ID. Use the List Assets template to find it.
  • See the Spotify Ads API reference for the response fields.

Audiences​

List Audiences

Lists the custom and lookalike audiences that an ad account can use, with each audience's size and status. Results are paged automatically, 50 per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Audience

Retrieves one audience with its type, size range, status, sources and events.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Audience ID. Use the List Audiences template to find it.
  • See the Spotify Ads API reference for the response fields.

List Audience Eligible Datasets

Lists the datasets, and their events, that an ad account can build custom audiences from. Returns up to 50 datasets.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Targeting and estimates​

List Ad Categories

Lists the ad categories with each category's ID, name and parent. Use the ID as an ad set's category.

  • Optionally, enter a keyword in Search to filter the categories. Leave it empty to list every category.
  • See the Spotify Ads API reference for the response fields.

List Geo Targets

Lists the targetable geos in a country (cities, regions, DMAs and postal codes) with the IDs to use in an ad set's geo_targets. Results are paged automatically, 1,000 per page.

  • Enter the Country Code (ISO 3166-1 alpha-2, default US) whose geos to list.
  • See the Spotify Ads API reference for the response fields.

Search Artist Targets

Searches artists by name and returns the IDs to use in an ad set's artist_ids targeting.

  • Enter the artist name to search for in Search. Matching is a case-insensitive wildcard match.
  • See the Spotify Ads API reference for the response fields.

List Genre Targets

Lists every targetable music genre with the IDs to use in an ad set's genre_ids.

List Interest Targets

Lists every targetable interest, with its subtargets and the IDs to use in an ad set's interest_ids.

List Language Targets

Lists every targetable language with its ID and name.

List Playlist Targets

Lists every targetable playlist theme with the IDs to use in an ad set's playlist_ids.

List Episode Topic Targets

Lists every targetable podcast episode topic with its ID and name.

List Sensitive Topic Targets

Lists the sensitive topics that an ad set can exclude, with each topic's ID and name.

Search Podcast Shows

Searches podcast shows by name in a market and returns each show's ID and images.

  • Enter the show name to search for in Search. Matching is a case-insensitive wildcard match.
  • Enter the Market (ISO 3166-1 alpha-2, default US). Only shows available in that market are returned.
  • See the Spotify Ads API reference for the response fields.

Estimate Audience

Forecasts the reach, impressions, frequency and CPM for planned ad set settings, and suggests a bid. Spotify serves this read as a POST request; it does not create anything.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Start Date of the planned flight in UTC. The default is tomorrow.
  • Enter the End Date of the planned flight in UTC. The default is 31 days from today.
  • Enter the Asset Format of the creative (default AUDIO).
  • Enter the Delivery Goal the ad set optimizes for (default IMPRESSIONS).
  • Enter the Bid Strategy (default MAX_BID).
  • Enter the Bid Micro Amount in millionths of the currency unit (default 10000000, which is 10.00).
  • Enter the Budget as a JSON object with micro_amount, type (DAILY or LIFETIME) and currency. The default is a daily budget of 5.00 USD.
  • Enter the Targets as a JSON object with the planned targeting, such as geo_targets, age_ranges, genders, placements, genre_ids and interest_ids. The default targets adults 18 to 65 in the US on music placements. Use the targeting templates in this group to find IDs.
  • See the Spotify Ads API reference for the response fields.

Estimate Bid

Returns the recommended bid range for planned ad set settings. Spotify serves this read as a POST request; it does not create anything.

  • Enter the Asset Format of the creative (default AUDIO).
  • Enter the Delivery Goal the ad set optimizes for (default IMPRESSIONS).
  • Enter the Bid Strategy (default MAX_BID).
  • Enter the ISO 4217 Currency of the estimate (default USD).
  • Enter the Targets as a JSON object with the planned targeting, such as geo_targets, age_ranges, genders, placements, genre_ids and interest_ids. The default targets adults 18 to 65 in the US on music placements. Use the targeting templates in this group to find IDs.
  • See the Spotify Ads API reference for the response fields.

Get Reserved Pricing

Quotes the fixed CPM for a Reserved Music or Reserved Podcasts buy. Spotify serves this read as a POST request; it does not book anything.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Ad Product: FPMNG (Reserved Music, default) or CONTENT (Reserved Podcasts).
  • Enter the Start Date of the planned flight in UTC. The default is tomorrow.
  • Enter the End Date of the planned flight in UTC. The default is 31 days from today.
  • Enter the Asset Format of the creative (default AUDIO).
  • Enter the Targets as a JSON object with the planned targeting, such as geo_targets, age_ranges, genders, placements, genre_ids and interest_ids. The default targets adults 18 to 65 in the US on music placements. Use the targeting templates in this group to find IDs.
  • See the Spotify Ads API reference for the response fields.

Reporting​

Get Aggregate Report

Reads campaign, ad set, ad or ad account metrics, such as impressions, clicks, spend and reach, for a date range, by day, hour or lifetime. Results are paged automatically with Spotify's continuation token, 50 rows per page.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Entity Type that each row reports on: CAMPAIGN (default), AD_SET, AD or AD_ACCOUNT.
  • Enter the Metrics as a comma-separated list of metric names (default IMPRESSIONS,CLICKS,CTR,SPEND,REACH,FREQUENCY). See the metrics glossary for the names.
  • Enter the Granularity: DAY (default, one row per entity per day), HOUR or LIFETIME.
  • Enter the Report Start in UTC, in whole hours. The default is 7 days ago at 00:00 UTC.
  • Enter the Report End in UTC, in whole hours. The default is today at 00:00 UTC.
  • See the Spotify Ads API reference for the response fields.

Get Aggregated Totals

Reads deduplicated totals, such as reach, frequency and spend, across up to 50 campaigns, ad sets or ads. Reach and frequency are deduplicated across the entities rather than summed.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Entity Type of the IDs to total: CAMPAIGN (default), AD_SET or AD. Spotify does not support AD_ACCOUNT here; use Get Aggregate Report for account totals.
  • Enter the Entity IDs to total across, comma-separated (at most 50), all of the selected entity type. Use the campaign, ad set or ad list templates to find them.
  • Keep the Granularity at LIFETIME (default). This template does not send a date range, which Spotify requires for DAY.
  • Enter the Metrics as a comma-separated list of metric names (default IMPRESSIONS,CLICKS,CTR,SPEND,REACH,FREQUENCY). See the metrics glossary for the names.
  • See the Spotify Ads API reference for the response fields.

Get Audience Insight Report

Reads lifetime metrics for an ad account, broken down by an audience dimension such as platform, age, gender, country or genre.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Insight Dimension to break the metrics down by (default PLATFORM). Spotify supports ACT_AND_SET, AGE, AUDIENCE, CITY, COUNTRY, FORMAT, GENDER, GENRE, INTERESTS, METRO, PLACEMENT, PLACEMENT_TYPE, PLATFORM, PODCAST_EPISODE_TOPIC, REGION and TONE.
  • Enter the Metrics as a comma-separated list of metric names (default IMPRESSIONS,CLICKS,CTR,SPEND,REACH,FREQUENCY). See the metrics glossary for the names.
  • See the Spotify Ads API reference for the response fields.

Run CSV Report

Runs a CSV report end to end and reads its rows into the Nexset: it requests the report, polls its status until it is READY, then downloads the CSV. See Asynchronous CSV reports for how it works.

  • Side effect: every run of this source creates a new report, which appears in the Reports section of Spotify Ads Manager.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter a Report Name of 2 to 120 characters, using only letters, digits, _ and - (default Nexla_report). The report appears under this name in Spotify Ads Manager.
  • Enter the Granularity: DAY (default, one row per day) or LIFETIME.
  • Enter the Dimensions as a JSON array of column names (default ["CAMPAIGN_NAME","AD_SET_NAME"]). The lowest level in the list sets what each row reports on.
  • Enter the Metrics as a JSON array of metric names (default ["IMPRESSIONS_ON_SPOTIFY","CLICKS","SPEND","REACH","FREQUENCY"]). See the metrics glossary for the names.
  • Enter the Statuses of the entities to include, as a JSON array (default ["ACTIVE","COMPLETED","PAUSED","STOPPED"]).
  • Enter the Report Start in UTC, in whole hours. The default is 7 days ago at 00:00 UTC.
  • Enter the Report End in UTC, in whole hours. The default is today at 00:00 UTC.
  • See the Spotify Ads API reference for the response fields.

Get Async Report Status

Reads the status of an asynchronous CSV report (PROCESSING, READY, EXPIRED or FAILED), and its download URL in report_url once it is READY.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Report ID returned by the Create Async Report destination.
  • See the Spotify Ads API reference for the response fields.

Datasets, pixels and mobile apps​

List Business Datasets

Lists a business's measurement datasets with each dataset's pixel, Conversions API (CAPI) integration, ad set count and event status.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Dataset

Retrieves one dataset with its pixel, CAPI integration and the ad accounts it is shared with. Use it to find pixel, CAPI connection and integration IDs.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Dataset ID. Use the List Business Datasets template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Dataset Diagnostics

Reads the event diagnostics time series for a dataset's pixel and CAPI data sources.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Dataset ID. Use the List Business Datasets template to find it.
  • Enter the Granularity of the diagnostics time series (default DAILY).
  • See the Spotify Ads API reference for the response fields.

List Ad Account Datasets

Lists the datasets that are shared with an ad account.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Pixel

Retrieves one pixel with its domain, events, received events and automatic event capture settings.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Pixel ID: the pixel.id value returned by the Get Dataset template.
  • See the Spotify Ads API reference for the response fields.

Get CAPI Integration

Retrieves one Conversions API integration with its name, dataset and the events it has received.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the CAPI Connection ID: the capi_integration.capi_connection_id value returned by the Get Dataset template.
  • See the Spotify Ads API reference for the response fields.

List Business Mobile Apps

Lists a business's mobile apps with each app's platform, store URLs, measurement partner and dataset. Results are paged automatically, 50 per page.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the response fields.

List Ad Account Mobile Apps

Lists the mobile apps that are shared with an ad account. Results are paged automatically, 50 per page.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the response fields.

Get Mobile App

Retrieves one mobile app with its platform, store URLs and measurement partner.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Mobile App ID. Use the List Business Mobile Apps template to find it.
  • See the Spotify Ads API reference for the response fields.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Asynchronous CSV reports​

Spotify builds CSV reports asynchronously: you request a report, Spotify generates it in the background, and you download the CSV once it is ready. The connector supports this in two ways:

  • Run CSV Report (source) does the whole process in one source. On each run, it:

    1. requests a report for the ad account, with the dimensions, metrics, statuses, granularity and date range from the template settings, and gets back the report ID;
    2. polls the report's status until it is READY, and stops with an error if Spotify reports FAILED;
    3. downloads the CSV from the report's report_url and reads each row of the CSV as a record.
  • Create Async Report (destination) and Get Async Report Status (source) split the process: send a record with the report definition to the destination to request a report, then read the report ID's status and report_url with the source until the status is READY, and download the CSV from that URL. Spotify also lists every report, with its download link, in the Reports section of Spotify Ads Manager. A report's status changes to EXPIRED once the CSV is no longer available.

Spotify allows 30 report requests per 30 seconds per app, so avoid scheduling many CSV report sources to run at the same time. For row-level metrics without a CSV, use Get Aggregate Report, which reads metrics directly as JSON.

Manual configuration​

Spotify Ads data sources can also be manually configured to ingest data from any valid Spotify Ads API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or optional filters that the templates do not send, such as status or name filters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers. Spotify Ads endpoint URLs take the form https://api-partner.spotify.com/ads/v3/.... See the Spotify Ads API reference for the available endpoints.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Spotify Ads data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination​

Click the + icon on the Nexset that will be sent to the Spotify Ads destination, and select the Send to Destination option from the menu. Select the Spotify Ads connector from the list of available destination connectors, then select the credential that will be used to connect to Spotify Ads, and click Next; or, create a new Spotify Ads credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Spotify Ads endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Each record in the Nexset is sent as the JSON body of one request, one record at a time, so shape each record to match the request body that Spotify documents for the endpoint. ID settings, such as an ad account or campaign ID, are fixed on the destination and apply to every record it sends. Templates are marked Spends budget when they create or change live campaigns, ad sets or ads that can spend money, and Side effect when they delete data or remove access in a way that cannot be undone from Nexla.

Businesses and members​

Create Business

Creates a business from each record. A record carries name, type, business_admin_name and business_admin_email.

Update Business

Renames a business. A record carries the new name.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the request body fields.

Invite Business Member

Invites a user to a business by email. A record carries email_address, business_role and, optionally, ad_account_invitations.

  • Spotify emails the invitation to the address in each record.
  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the request body fields.

Cancel Business Invitation

Cancels a pending invitation to a business.

  • Side effect: the invitation can no longer be accepted.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Invitation ID: the business_invitation_id value returned by the List Business Invitations template.
  • See the Spotify Ads API reference for the request body fields.

Accept Business Invitation

Accepts an invitation to a business and creates the user's business profile. A record carries invitation_id, name and email_address.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Business Member

Updates a business member's profile. A record carries any of name, email_address and has_marketing_opt_in.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Member ID: the member_id value returned by the List Business Members template.
  • See the Spotify Ads API reference for the request body fields.

Update Business Member Role

Changes a member's business role. A record carries the new role.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Member ID: the member_id value returned by the List Business Members template.
  • See the Spotify Ads API reference for the request body fields.

Remove Business Member

Removes a member from a business.

  • Side effect: removes the member from the business and from all of its ad accounts.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Member ID: the member_id value returned by the List Business Members template.
  • See the Spotify Ads API reference for the request body fields.

Ad accounts and members​

Create Ad Account

Creates an ad account in a business from each record. A record carries fields such as name, type, industry, country_code, legal_entity_name, bill_to_address and website.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Ad Account

Updates an ad account's name, industry, website, legal entity, tax IDs or billing address. A record carries the fields to change.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Add Ad Account Member

Adds a business member to an ad account. A record carries member_id and role.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Ad Account Member Role

Changes a member's role on an ad account. A record carries the new role.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Member ID: the member_id value returned by the List Ad Account Members template.
  • See the Spotify Ads API reference for the request body fields.

Remove Ad Account Member

Removes a member from an ad account.

  • Side effect: the member loses access to the ad account.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Member ID: the member_id value returned by the List Ad Account Members template.
  • See the Spotify Ads API reference for the request body fields.

Campaigns​

Create Campaign

Creates a live campaign from each record. A record carries name, objective and, optionally, purchase_order.

  • Spends budget: the ad sets and ads you add to a live campaign can start delivering and spending budget.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Campaign

Updates a live campaign. A record carries any of name, purchase_order and status.

  • Spends budget: setting status to ACTIVE resumes delivery and spending.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Campaign ID. Use the List Campaigns template to find it.
  • See the Spotify Ads API reference for the request body fields.

Create Draft from Campaign

Copies a published campaign into a new draft campaign, which you can change and publish later.

  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Campaign ID. Use the List Campaigns template to find it.
  • See the Spotify Ads API reference for the request body fields.

Create Campaign Draft

Creates a draft campaign, which is not delivered until it is published. A record carries name, objective and, optionally, purchase_order.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Campaign Draft

Updates a draft campaign. A record carries the fields to change.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Campaign ID. Use the List Campaign Drafts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Publish Campaign Draft

Validates or publishes a draft campaign with its draft ad sets and ads. A record carries action (VALIDATE or PUBLISH) and draft_hierarchy_version. Send VALIDATE first to check the drafts without publishing them.

  • Spends budget: PUBLISH makes the campaign, its ad sets and its ads live, and they can start delivering and spending budget.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Campaign ID. Use the List Campaign Drafts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Delete Campaign Draft

Deletes a draft campaign.

  • Side effect: permanently deletes the draft campaign.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Campaign ID. Use the List Campaign Drafts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Ad sets​

Create Ad Set

Creates a live ad set from each record. A record carries fields such as name, campaign_id, category, budget, targets and asset_format, plus the ad set's schedule and bid.

  • Spends budget: a live ad set has a budget and a bid, and its ads can start delivering and spending budget.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Ad Set

Updates a live ad set: its budget, bid, schedule, targeting or delivery. A record carries the fields to change.

  • Spends budget: changes take effect on a live ad set, and turning delivery on resumes spending.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Ad Set ID. Use the List Ad Sets template to find it.
  • See the Spotify Ads API reference for the request body fields.

Create Draft from Ad Set

Copies a published ad set into a new draft ad set.

  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Ad Set ID. Use the List Ad Sets template to find it.
  • See the Spotify Ads API reference for the request body fields.

Create Ad Set Draft

Creates a draft ad set, which is not delivered until its campaign draft is published. A record carries fields such as campaign_id, name, dates, budget, bid and targets.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Bulk Create Ad Set Drafts

Creates several draft ad sets in one request. A record carries an ad_set_drafts array. Spotify creates all of them or none.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Ad Set Draft

Updates a draft ad set. A record carries the fields to change.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Ad Set ID. Use the List Ad Set Drafts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Delete Ad Set Draft

Deletes a draft ad set.

  • Side effect: permanently deletes the draft ad set.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Ad Set ID. Use the List Ad Set Drafts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Bulk Delete Ad Set Drafts

Deletes several draft ad sets in one request. Spotify deletes all of them or none.

  • Side effect: permanently deletes the draft ad sets and their draft ads.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Ad Set IDs to delete, comma-separated (at most 40). Use the List Ad Set Drafts template to find them.
  • See the Spotify Ads API reference for the request body fields.

Ads​

Create Ad

Creates an ad in a live ad set from each record. A record carries fields such as ad_set_id, name, advertiser_name, assets, call_to_action, tagline and dates. The response includes any reject reasons for the ad.

  • Spends budget: an ad in a live ad set can start delivering and spending budget.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Ad

Updates a live ad: delivery on or off, schedule, assets or call to action. A record carries the fields to change.

  • Spends budget: changes take effect on a live ad, and turning delivery on resumes spending.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Ad ID. Use the List Ads template to find it.
  • See the Spotify Ads API reference for the request body fields.

Create Draft from Ad

Copies a published ad into a new draft ad.

  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Ad ID. Use the List Ads template to find it.
  • See the Spotify Ads API reference for the request body fields.

Create Ad Draft

Creates a draft ad, which is not delivered until it is published. A record carries fields such as ad_set_id, name, advertiser_name, assets, call_to_action and tagline.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Bulk Create Ad Drafts

Creates several draft ads in one request. A record carries an ad_drafts array. Spotify creates all of them or none.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Ad Draft

Updates a draft ad. A record carries the fields to change.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Ad ID. Use the List Ad Drafts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Delete Ad Draft

Deletes a draft ad.

  • Side effect: permanently deletes the draft ad.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Ad ID. Use the List Ad Drafts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Bulk Delete Ad Drafts

Deletes several draft ads in one request. Spotify deletes all of them or none.

  • Side effect: permanently deletes the draft ads.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Draft Ad IDs to delete, comma-separated (at most 100). Use the List Ad Drafts template to find them.
  • See the Spotify Ads API reference for the request body fields.

Assets​

Create Asset

Creates an asset record from each record. A record carries asset_type, asset_subtype and name. This creates the asset's metadata only; Spotify takes the media file in a separate upload, which this template does not perform.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Asset

Updates an asset's metadata. A record carries name and asset_type.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Asset ID. Use the List Assets template to find it.
  • See the Spotify Ads API reference for the request body fields.

Audiences​

Create Audience

Creates a custom or lookalike audience. A record carries the audience definition, such as its name, type, sources, datasets, events and lookback days.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Edit Audience

Edits an audience. A record carries the fields to change.

  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Audience ID. Use the List Audiences template to find it.
  • See the Spotify Ads API reference for the request body fields.

Delete Audience

Deletes an audience.

  • Side effect: permanently deletes the audience, and ad sets that target it lose it.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Audience ID. Use the List Audiences template to find it.
  • See the Spotify Ads API reference for the request body fields.

Create Audience Upload URL

Returns a signed upload URL, and the new audience's ID, for a user list file. Uploading the file to that URL is a separate step that this template does not perform.

  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Replace Audience Upload URL

Returns a signed URL for replacing an existing audience's user list file.

  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • Enter the Audience ID. Use the List Audiences template to find it.
  • See the Spotify Ads API reference for the request body fields.

Reporting​

Create Async Report

Requests an asynchronous CSV report and returns its report ID. Read the report's status and download URL with the Get Async Report Status source. A record carries name, granularity, dimensions, metrics, report_start and report_end, and can also carry statuses and campaign_ids.

  • Each record creates one report, which appears in the Reports section of Spotify Ads Manager. No campaign data is changed.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Datasets, pixels and mobile apps​

Create Dataset

Creates a measurement dataset in a business. A record carries name and integration_ids.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Dataset

Renames a dataset. A record carries the new name.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Dataset ID. Use the List Business Datasets template to find it.
  • See the Spotify Ads API reference for the request body fields.

Share Dataset with Ad Account

Shares a business dataset with an ad account.

  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Dataset ID. Use the List Business Datasets template to find it.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Unshare Dataset from Ad Account

Stops sharing a dataset with an ad account.

  • Side effect: the ad account loses access to the dataset, and its ad sets lose that measurement.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Dataset ID. Use the List Business Datasets template to find it.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Remove Integration from Dataset

Detaches a pixel or CAPI integration from a dataset. Spotify moves the integration into a new dataset.

  • Side effect: the dataset stops receiving events from that integration.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Dataset ID. Use the List Business Datasets template to find it.
  • Enter the Integration ID: the pixel.integration_id or capi_integration.integration_id value returned by the Get Dataset template.
  • See the Spotify Ads API reference for the request body fields.

Create Pixel

Creates a pixel in a business. A record carries domain, name, dataset_id, aam_opt_in and aam_fields.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Pixel

Updates a pixel's domain or name. A record carries domain and name.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Pixel ID: the pixel.id value returned by the Get Dataset template.
  • See the Spotify Ads API reference for the request body fields.

Create CAPI Integration

Creates a Conversions API integration. A record carries name and dataset_id.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update CAPI Integration

Renames a Conversions API integration. A record carries the new name.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the CAPI Connection ID: the capi_integration.capi_connection_id value returned by the Get Dataset template.
  • See the Spotify Ads API reference for the request body fields.

Delete CAPI Auth Token

Revokes a Conversions API auth token.

  • Side effect: servers that use the token can no longer send events.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the CAPI Connection ID: the capi_integration.capi_connection_id value returned by the Get Dataset template.
  • Enter the CAPI Token ID. Spotify Ads Manager shows the token under the CAPI integration.
  • See the Spotify Ads API reference for the request body fields.

Create Mobile App

Registers a mobile app in a business. A record carries a mobile_app object with the app's name, platform, store URL and measurement partner.

  • Enter the Business ID. Use the List Businesses template to find it.
  • See the Spotify Ads API reference for the request body fields.

Update Mobile App

Updates a mobile app. A record carries the fields to change.

  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Mobile App ID. Use the List Business Mobile Apps template to find it.
  • See the Spotify Ads API reference for the request body fields.

Share Mobile App with Ad Account

Shares a business mobile app with an ad account.

  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Mobile App ID. Use the List Business Mobile Apps template to find it.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Unshare Mobile App from Ad Account

Stops sharing a mobile app with an ad account.

  • Side effect: the ad account loses access to the mobile app.
  • The record's content is not sent; each record repeats the same request, so send a single record.
  • Enter the Business ID. Use the List Businesses template to find it.
  • Enter the Mobile App ID. Use the List Business Mobile Apps template to find it.
  • Enter the Ad Account ID. Use the List Business Ad Accounts template to find it.
  • See the Spotify Ads API reference for the request body fields.

Manual configuration​

Spotify Ads destinations can also be manually configured to send data to any valid Spotify Ads API endpoint. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

The Spotify Ads API expects JSON request bodies for create and update requests. Include the business, ad account and object IDs in the endpoint URL.

Save & activate​

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Spotify Ads endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to the Spotify Ads endpoint until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.