원클릭으로
monitor
// 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.
// 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.
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.
Pull Spotify Ads API reporting data — aggregate metrics, audience insights, or async CSV reports.
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.
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 | monitor |
| description | 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. |
| argument-hint | [campaign_id] | [--all] |
| allowed-tools | ["Read","Bash","AskUserQuestion"] |
Diagnose delivery problems across active campaigns. Goes beyond the dashboard by running diagnostic checks and recommending specific actions.
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.--all → Health check all active campaigns<campaign_id> (UUID) → Deep health check on a specific campaign (includes ad set and ad level diagnostics)Execute these calls to gather the data needed for diagnostics:
curl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/campaigns?statuses=ACTIVE&limit=50&sort_direction=DESC"
curl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/ad_sets?statuses=ACTIVE&limit=50&sort_direction=DESC"
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=REACH&fields=CLICKS&fields=CTR&fields=FREQUENCY&\
granularity=DAY&\
report_start=$(date -u +%Y-%m-%dT00:00:00Z)&\
report_end=$(date -u +%Y-%m-%dT00:00:00Z)&\
entity_status_type=CAMPAIGN&\
statuses=ACTIVE&\
limit=50"
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=REACH&fields=CLICKS&\
granularity=LIFETIME&\
entity_status_type=CAMPAIGN&\
statuses=ACTIVE&\
limit=50"
Run these diagnostics against the fetched data:
For each active campaign, compare spend progress to flight progress:
DAILY budgets: Sum the daily budgets of all active ad sets under the campaign. Compare today's spend to the total daily budget.
$142.50 / $200.00 daily (71%)LIFETIME budgets: Compare total lifetime spend to total lifetime budget, and compare against elapsed flight percentage.
elapsed_pct = (today - start_date) / (end_date - start_date) * 100spend_pct = total_spend / total_budget * 100$2,100 / $5,000 lifetime (42% spent, 35% of flight elapsed)Alert levels:
For LIFETIME budgets, project when the budget will run out at the current daily burn rate:
daily_burn = lifetime_spend / days_elapseddays_remaining_at_pace = (budget - spend) / daily_burnprojected_end = today + days_remaining_at_paceFlag if:
end_time → "May exhaust budget early"end_time → "Likely to underspend"=== Campaign Health Check ===
Checked: 3 active campaigns, 7 active ad sets
Time: 2026-05-14 14:30 UTC
| Campaign | Status | Spend Today | Pacing | Issues |
|----------|--------|-------------|--------|--------|
| Summer Promo | OK | $142.50 / $200 daily (71%) | On track | — |
| Q2 Brand | WARNING | $28.00 / $100 daily (28%) | Underpacing | 1 stalled ad set |
| Podcast Launch | CRITICAL | $0.00 / $75 daily (0%) | Stalled | No delivery today |
Issues Found (2):
1. [WARNING] Q2 Brand: Spending at 28% of daily budget with 62% of day elapsed
→ Consider increasing bid or broadening targeting. Run: /spotify-ads-api:dashboard <campaign_id>
2. [CRITICAL] Podcast Launch: Zero impressions today (campaign started 2026-05-12)
→ Campaign may have delivery issues. Check ad approval status with: /spotify-ads-api:monitor <campaign_id>
If no issues are found:
All 3 active campaigns are healthy. No issues detected.
<campaign_id>)curl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/campaigns/$CAMPAIGN_ID"
curl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/ad_sets?campaign_ids=$CAMPAIGN_ID&limit=50"
curl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
-H "$SDK_HEADER" \
"$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/ads?campaign_ids=$CAMPAIGN_ID&limit=50"
Extract active and paused ad set IDs from Step 2 and build repeated query parameters before fetching ad set metrics:
AD_SET_IDS_QUERY="entity_ids=<AD_SET_ID_1>&entity_ids=<AD_SET_ID_2>"
Use the ad set IDs directly because non-LIFETIME aggregate reports require entity_ids_type to match entity_type. If the campaign has more than 50 ad sets, chunk report requests in groups of 50.
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=AD_SET&\
fields=IMPRESSIONS&fields=SPEND&fields=CLICKS&fields=REACH&fields=CTR&fields=FREQUENCY&fields=COMPLETES&\
granularity=DAY&\
report_start=$(date -u +%Y-%m-%dT00:00:00Z)&\
report_end=$(date -u +%Y-%m-%dT00:00:00Z)&\
${AD_SET_IDS_QUERY}&\
entity_ids_type=AD_SET&\
entity_status_type=AD_SET&\
limit=50"
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=AD_SET&\
fields=IMPRESSIONS&fields=SPEND&fields=CLICKS&fields=REACH&fields=FREQUENCY&\
granularity=LIFETIME&\
${AD_SET_IDS_QUERY}&\
entity_ids_type=AD_SET&\
entity_status_type=AD_SET&\
include_parent_entity=true&\
limit=50"
In addition to the pacing, stalled, and exhaustion checks from the account-wide mode, the deep check adds:
REJECTED — flag with recommendation to review and re-create.PENDING where created_at is more than 24 hours ago — flag as unusually slow approval.delivery: OFF under an ACTIVE ad set — flag as potentially unintentional.=== Summer Promo — Deep Health Check ===
Campaign: ACTIVE | Objective: REACH | Created: 2026-04-01
Ad Set Health:
| Ad Set | Format | Budget | Spend Today | Pacing | Freq | Issues |
|--------|--------|--------|-------------|--------|------|--------|
| US 18-34 Audio | AUDIO | $75/day | $68.50 (91%) | OK | 1.8 | — |
| US 25-54 Video | VIDEO | $50/day | $12.00 (24%) | WARNING | 0.4 | Underpacing |
Ad Health:
| Ad | Ad Set | Status | Delivery | Issues |
|----|--------|--------|----------|--------|
| 30s Spot A | US 18-34 Audio | APPROVED | ON | — |
| 30s Spot B | US 18-34 Audio | REJECTED | — | Rejected |
| 15s Video | US 25-54 Video | PENDING | ON | Pending >24h |
Recommendations:
1. "US 25-54 Video" is underpacing at 24% spend. Consider:
- Broadening targeting (current: US, ages 25-54, VIDEO)
- Increasing bid cap
- Run: /spotify-ads-api:ads ad-sets get <ad_set_id>
2. "30s Spot B" was rejected. Review and re-create via /spotify-ads-api:ads ads create
3. "15s Video" has been pending approval for >24h — check if creative meets format requirements.
After displaying results, suggest recurring checks only when the host environment supports scheduled tasks or automations:
To monitor automatically, schedule a recurring run of:
/spotify-ads-api:monitor --all
auto_execute is true, execute all API calls directly and display the health check.auto_execute is false, present the curl commands and ask for confirmation before executing.HTTP_STATUS: line from curl output to determine success or failure before interpreting the response body.aggregate_reports: Already in dollars — display directly as $X.XX.micro_amount from entity details: In micro-units — divide by 1,000,000 to get dollars.156,234).0.79%).71%).