// Pull Spotify Ads API reporting data — aggregate metrics, audience insights, or async CSV reports.
Manage Spotify Ads API ad sets and ads — list, create, get, or update.
This skill should be used when the user asks to "call the Spotify Ads API", "create a Spotify ad campaign", "manage Spotify ads", "pull Spotify ad reports", "set up ad sets or ads", "upload ad assets", "target audiences on Spotify", "check campaign status", "get ad account info", "look up API schema or fields", "check what targeting options exist", or asks about Spotify advertising endpoints, request/response formats, enum values, or authentication.
Create a full campaign (campaign + ad sets + ads) from a plain-text description. Parses natural language into structured API calls.
Export Spotify Ads API campaign data to CSV — full campaign hierarchies with ad sets, ads, targeting, budgets, and performance metrics for offline review, campaign analysis, or budget reconciliation.
Check Spotify Ads API campaign health — pacing, delivery issues, budget burn rate, stalled campaigns, and underpacing alerts. Use for one-shot health checks or recurring monitoring when the host supports scheduled automations.
Generate Spotify Ads campaign strategy from a landing page, product or business page, brand brief, location page, uploaded creative assets, existing Spotify Ads assets, or a natural-language business goal. Use when the user asks for the best campaign structure, targeting plan, audience plan, budget split, creative rotation, API-ready campaign plan, or pre-build recommendations before creating Spotify campaigns.
| name | report |
| description | Pull Spotify Ads API reporting data — aggregate metrics, audience insights, or async CSV reports. |
| argument-hint | aggregate | insights | async-create | async-status <report_id> |
| allowed-tools | ["Read","Bash","AskUserQuestion"] |
Pull reporting data from the Spotify Ads API. Read settings from the active platform settings file.
access_token, ad_account_id, and auto_execute from the active platform settings file:
.codex/spotify-ads-api.local.md, then fall back to .claude/spotify-ads-api.local.md..claude/spotify-ads-api.local.md, then fall back to .codex/spotify-ads-api.local.md.https://api-partner.spotify.com/ads/v3/spotify-ads-api:configure first.version: .codex-plugin/plugin.json on Codex or .claude-plugin/plugin.json on Claude.SDK_PRODUCT to codex-plugin on Codex or claude-code-plugin on Claude. Set SDK_HEADER="X-Spotify-Ads-Sdk: $SDK_PRODUCT/$PLUGIN_VERSION" and include -H "$SDK_HEADER" on all API requests.aggregate (default if no argument)Get aggregated campaign metrics.
Prompt for:
CAMPAIGN, AD_SET, AD, or AD_ACCOUNTfields, NOT report_fields.
Suggested: IMPRESSIONS, SPEND, CLICKS, REACH, FREQUENCY, COMPLETES
Full list: IMPRESSIONS, SPEND, CLICKS, REACH, FREQUENCY, LISTENERS, NEW_LISTENERS,
STREAMS, COMPLETES, COMPLETION_RATE, STARTS, FIRST_QUARTILES, MIDPOINTS, THIRD_QUARTILES,
VIDEO_VIEWS, CTR, OFF_SPOTIFY_IMPRESSIONSImportant: Array query parameters must use repeated parameter names, NOT comma-separated. Validation guardrails:
limit must be 1-50.entity_type must be exactly CAMPAIGN, AD_SET, AD, or AD_ACCOUNT.entity_ids is present, always include entity_ids_type.statuses is present, always include entity_status_type; it must match the status owner.segments, dimensions, groupBy, or async-report metrics names on aggregate reports.report_start or report_end when granularity=LIFETIME; use DAY for date-ranged reporting.DAY, use UTC midnight timestamps for both start and end, e.g. 2026-05-01T00:00:00Z.PAGE_VIEWS, LEADS, ADD_TO_CART, PURCHASES, REVENUE, RETURN_ON_AD_SPEND, AVERAGE_ORDER_VALUE, START_CHECKOUT, and SIGN_UPS.curl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/aggregate_reports?\
entity_type=CAMPAIGN&\
fields=IMPRESSIONS&fields=SPEND&fields=CLICKS&fields=REACH&fields=FREQUENCY&\
granularity=LIFETIME&\
limit=50"
Granularity constraints:
LIFETIME: do not send report_start or report_endDAY: date range must be within 90 days and both timestamps must be UTC midnightHOUR: date range must be within the last 2 weeksFormat the response as a readable table with stats broken out per entity. Filter out rows with zero impressions for cleaner output.
totalsGet deduplicated metrics aggregated across multiple campaigns, ad sets, or ads. Reach and frequency are deduplicated across all specified entities.
Prompt for:
CAMPAIGN, AD_SET, or AD (AD_ACCOUNT not supported here; use aggregate instead)LIFETIME or DAY (HOUR not supported for totals)IMPRESSIONS, CLICKS, CTR, REACH, FREQUENCYcurl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/aggregate_reports/totals?\
entity_type=AD_SET&\
entity_ids=$ID1&entity_ids=$ID2&\
granularity=LIFETIME&\
fields=IMPRESSIONS&fields=REACH&fields=FREQUENCY"
Format the response showing aggregated stats per time period (one row for LIFETIME, one row per day for DAY).
insightsGet audience insight breakdowns.
Prompt for:
ACT_AND_SET, AGE, AUDIENCE, CITY, COUNTRY, FORMAT,
GENDER, GENRE, INTERESTS, METRO, PLACEMENT, PLATFORM,
PODCAST_EPISODE_TOPIC, REGION, or TONEfields params. Insight reports do not allow
E_CPCL, FREQUENCY, OFF_SPOTIFY_IMPRESSIONS, PAID_LISTENS_FREQUENCY,
SKIPS, SPEND, STARTS, or UNMUTES.entity_ids is set; use AD_SET for insight reportsAD_SET for insight reports)Insight report guardrails:
entity_ids value at a time, and it must be an ad set ID.entity_ids_type=AD_SET when entity_ids is present. Do not use CAMPAIGN.entity_type on insight reports; entity_type=AD_SET does not substitute for entity_ids_type=AD_SET.report_start, report_end, granularity, or limit; insight reports are LIFETIME only.insight_dimension values. Do not use LOCATION, GEO, DMA, STATE, ZIP, POSTAL, POSTAL_CODE, MARKET, DEVICE, OS, ARTIST, AGE_RANGE, or CITY_NAME.COUNTRY, region/state -> REGION, metro/DMA -> METRO, city -> CITY.curl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/insight_reports?\
insight_dimension=GENDER&\
fields=IMPRESSIONS&fields=CLICKS&fields=CTR&\
entity_ids=$ENTITY_IDS&\
entity_ids_type=AD_SET"
Format results showing the breakdown by the selected dimension.
async-createCreate an async CSV report for download.
Prompt for:
ACT_AND_SET, AGE, AUDIENCE, CITY, COUNTRY, FORMAT, GENDER, GENRE, INTERESTS, METRO, PLACEMENT, PLATFORM, PODCAST_EPISODE_TOPIC, REGION, or TONE. Only supported with LIFETIME granularity.Async report guardrails:
dimensions are entity metadata columns only. Do not put CITY, COUNTRY, REGION, DMA, POSTAL_CODE, LOCATION, AGE, GENDER, PLATFORM, DEVICE, or OS in dimensions; use insight_dimension with granularity=LIFETIME for async CSV delivery insight breakdowns, or insight_reports for direct JSON insight results.dimensions and metrics, not groupBy, fields, dateRange, or entityType.granularity=DAY, include report_start; use UTC midnight timestamps for date boundaries.curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
-H "Content-Type: application/json" \
-d '{
"name": "...",
"granularity": "DAY",
"dimensions": ["CAMPAIGN_NAME", "AD_SET_NAME"],
"metrics": ["IMPRESSIONS_ON_SPOTIFY", "SPEND", "CLICKS"],
"report_start": "2025-01-01T00:00:00Z",
"report_end": "2025-01-31T00:00:00Z"
}' \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/async_reports"
After creating, show the report ID and suggest checking status with async-status.
async-status <report_id>Check the status of an async report and get the download URL when ready.
curl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/async_reports/$REPORT_ID"
If complete, display the download URL. If still processing, report the status and suggest checking again later.
auto_execute is true, execute directly.auto_execute is false, present the curl command and ask for confirmation.