Connect
Spotify Ads: connect, report and manage campaigns
TL;DR
Spotify Ads connects over OAuth to the Spotify Ads API (v3). The agent has 18 reads and 10 writes. Creates land paused; turning spend on, publishing a draft, audience writes and ad-account edits always wait for a person; by default every other change waits for your approval unless auto-approve is on. There is no delete.
Connect
- 1Once per app: an administrator accepts the Spotify Ads API Terms at https://adsmanager.spotify.com/api-terms. Until then Spotify answers every call with 403 "not allow-listed"; allowlisting can take up to about an hour.
- 2On Integrations, open the Spotify Ads card and press Connect. Sign in with a Spotify Ads Manager login that has a role on the ad account (an admin or editor role can change things; a viewer only reads).
- 3Each ad account the login reaches becomes a row. Refresh accounts (or the automatic refresh) adds new ones; Re-authorize renews the sign-in and keeps the rows and everything bound to them.
Tools
| Tool | Kind | What it does |
|---|---|---|
| list_businesses / list_ad_accounts / get_ad_account | Read | The businesses and ad accounts the login reaches; the selected account's record (billing address and tax id are never returned) |
| list_campaigns / get_campaign | Read | Campaigns: name, status, objective |
| list_ad_sets / get_ad_set | Read | Budget (whole units, daily or lifetime), bid strategy and bid, delivery, schedule, targets, review state |
| list_ads / get_ad | Read | Ads: status, delivery, rejection reasons, call to action, tracking, preview link |
| list_assets | Read | Audio, image and video assets and their processing state |
| report | Read | Aggregate report by campaign, ad set, ad or account; day, hour or lifetime |
| start_report_export / get_report_export | Read | A CSV export for longer or wider reports: start it, then poll until it is ready |
| estimate_audience | Read | Audience and bid forecast for an ad set shape (changes nothing) |
| list_targets | Read | Targeting catalogues: artists, genres, geos, interests, languages, playlists, podcast topics |
| get_change_history | Read | Who changed what (e-mail addresses are never returned) |
| get_account_health | Read | Whether the account can deliver: status, rejected / pending ads, ad sets Spotify paused, billing method |
| get | Read | Any other Ads API v3 read on the selected ad account, by path |
| create_campaign / update_campaign / set_campaign_status | Write | A paused campaign; rename or change the purchase order; status (ACTIVE always waits for a person) |
| create_ad_set / update_ad_set / set_ad_set_delivery | Write | An ad set with delivery off; budget, bid, schedule and targets; delivery (ON always waits for a person) |
| update_ad / set_ad_delivery | Write | Ad copy, call to action and tracking; delivery (ON always waits for a person) |
| create_asset | Write | An audio, image or video asset, uploaded from a public https URL (up to 20 MB) |
| mutate | Write | Any other Ads API v3 write on the selected ad account, by method and path (no DELETE) |
Over MCP and the REST API the names are spotify_ads__<tool> (for example spotify_ads__report). Spotify has no raw request lane: get and mutate are its gateways, bound to the selected ad account.
Approvals and safety
- By default every write waits for your approval card; with auto-approve on (per task, schedule or project) ordinary writes apply inside your spend caps and protected campaigns.
- Always a person's decision, on every lane and whatever the approval setting: a campaign set ACTIVE, an ad set's or ad's delivery set ON, publishing a draft, any audience write and edits to the ad-account record.
- New campaigns are created PAUSED and new ad sets and ads with delivery OFF — the tool sends off even where Spotify's own default is on.
- No delete: Spotify's Ads API has none for campaigns, ad sets or ads, and ARCHIVED or a DELETE through mutate is refused. Pause instead (fully reversible).
- Creates carry an idempotency key, so a retried step returns the object it already made instead of a second one; an asset create with an idempotencyKey returns the asset of the same type and exact name.
Money, reports and units
- Every argument and result is in whole units of the account currency (25 = 25.00). Write budget: { amount }, bid_amount and base_rate_amount; a field whose name contains "micro" is refused, because a micro value multiplied again would be a million times too large.
- Report days are UTC (Spotify reports have no account time zone) and the end day is included. A day or lifetime report covers at most 90 days; an hourly one only the last two weeks.
- A campaign, ad set or ad report by day or hour must name entity ids (Spotify's rule). When you name none, the tool uses the account's own entities (the first 50) and says so; an account with none returns an empty report.
- For more rows or a longer range, start_report_export makes a CSV export.
Account health
get_account_health gives a verdict (healthy, attention, suspended, not serving, no access) with the facts behind it: the account status and Spotify's stated reason, the login's role, rejected and pending ads, ad sets Spotify paused, and the billing method. A new account whose billing_type is UNSET is marked attention — nothing can run until billing is added in Spotify Ads Manager. Spotify publishes no advertiser-verification object, so verification is not reported. The same facts feed account-status alert rules.
Troubleshooting
| What you see | What it means | What to do |
|---|---|---|
| 403 "not allow-listed" | The Ads API Terms were not accepted for the app | Accept them at adsmanager.spotify.com/api-terms, wait up to an hour |
| "No billing method is set" in account health | The ad account has no billing method yet | Add billing in Spotify Ads Manager → Settings → Billing |
| An empty report | No campaigns yet, or nothing delivered in the window | Check list_campaigns; widen the dates (UTC, at most 90 days) |
| A refusal naming a micro field | Money was written in micro units | Use budget: { amount } / bid_amount in whole units |
| 401 or an expired sign-in | The Spotify grant was revoked or expired | Re-authorize on the Spotify Ads card — the rows stay |
Why the Web Playback SDK is not used
The Web Playback SDK is a browser player for Spotify Premium listeners. Spotify requires prior written approval for commercial use, it plays Spotify's catalogue and never an advertiser's ad audio, and Spotify's developer policy does not allow pairing its recordings with advertising. Ad audio and background music are the Ads API's own audio assets (create_asset with assetType AUDIO).
Platform overview: Spotify Ads.
Frequently asked questions
- Which Spotify Ads permissions does the connection ask for?
- None to choose: the Spotify Ads API defines no OAuth scopes. Access comes from the app accepting the Ads API Terms and the login's role on the ad account.
- Can the agent turn on a Spotify campaign?
- Only with a person's approval: setting a campaign active or delivery on always waits for a person, whatever the approval setting.
- Does it work over MCP and the REST API?
- Yes — the same tools as spotify_ads__<tool>, with the same approvals and limits; describe_tool shows each tool's policy.