report

What this skill does

# Spotify Ads API — Reporting

Pull reporting data from the Spotify Ads API. Read settings from the active platform settings file.

## Setup

1. Read `access_token`, `ad_account_id`, and `auto_execute` from the active platform settings file:
   - Codex: prefer `.codex/spotify-ads-api.local.md`, then fall back to `.claude/spotify-ads-api.local.md`.
   - Claude: prefer `.claude/spotify-ads-api.local.md`, then fall back to `.codex/spotify-ads-api.local.md`.
2. Base URL: `https://api-partner.spotify.com/ads/v3`
3. If neither settings file exists, instruct the user to run `/spotify-ads-api:configure` first.
4. Read the active platform manifest for the plugin `version`: `.codex-plugin/plugin.json` on Codex or `.claude-plugin/plugin.json` on Claude.
5. Set `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.

## Operations

### `aggregate` (default if no argument)
Get aggregated campaign metrics.

Prompt for:
- **entity_type** — What to report on: `CAMPAIGN`, `AD_SET`, `AD`, or `AD_ACCOUNT`
- **fields** — Metrics to include. **Parameter name is `fields`, 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_IMPRESSIONS
- **granularity** (HOUR, DAY, LIFETIME — default LIFETIME)
- **report_start** / **report_end** (ISO 8601; required for DAY/HOUR, do not send for LIFETIME)
- **entity_ids** + **entity_ids_type** (optional — filter to specific IDs)
- **include_parent_entity** (optional, boolean — include parent info for AD_SET/AD)

**Important:** 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`.
- If `entity_ids` is present, always include `entity_ids_type`.
- If `statuses` is present, always include `entity_status_type`; it must match the status owner.
- Do not use `segments`, `dimensions`, `groupBy`, or async-report `metrics` names on aggregate reports.
- Do not include `report_start` or `report_end` when `granularity=LIFETIME`; use `DAY` for date-ranged reporting.
- For `DAY`, use UTC midnight timestamps for both start and end, e.g. `2026-05-01T00:00:00Z`.
- Do not guess conversion metric names. Valid aggregate conversion-style fields include `PAGE_VIEWS`, `LEADS`, `ADD_TO_CART`, `PURCHASES`, `REVENUE`, `RETURN_ON_AD_SPEND`, `AVERAGE_ORDER_VALUE`, `START_CHECKOUT`, and `SIGN_UPS`.

```bash
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_end`
- `DAY`: date range must be within 90 days and both timestamps must be UTC midnight
- `HOUR`: date range must be within the last 2 weeks

Format the response as a readable table with stats broken out per entity. Filter out rows with zero impressions for cleaner output.

### `totals`
Get deduplicated metrics aggregated across multiple campaigns, ad sets, or ads. Reach and frequency are deduplicated across all specified entities.

Prompt for:
- **entity_type** (required) — `CAMPAIGN`, `AD_SET`, or `AD` (AD_ACCOUNT not supported here; use `aggregate` instead)
- **entity_ids** (required) — Up to 50 entity IDs to aggregate across
- **granularity** (required) — `LIFETIME` or `DAY` (HOUR not supported for totals)
- **fields** (required) — Metrics: `IMPRESSIONS`, `CLICKS`, `CTR`, `REACH`, `FREQUENCY`
- **report_start** / **report_end** (required for DAY, optional for LIFETIME)

```bash
curl -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).

### `insights`
Get audience insight breakdowns.

Prompt for:
- **insight_dimension** — `ACT_AND_SET`, `AGE`, `AUDIENCE`, `CITY`, `COUNTRY`, `FORMAT`,
  `GENDER`, `GENRE`, `INTERESTS`, `METRO`, `PLACEMENT`, `PLATFORM`,
  `PODCAST_EPISODE_TOPIC`, `REGION`, or `TONE`
- **fields** — Metrics to include. Use repeated `fields` params. Insight reports do not allow
  `E_CPCL`, `FREQUENCY`, `OFF_SPOTIFY_IMPRESSIONS`, `PAID_LISTENS_FREQUENCY`,
  `SKIPS`, `SPEND`, `STARTS`, or `UNMUTES`.
- **entity_ids** — One ad set ID to analyze
- **entity_ids_type** — Required when `entity_ids` is set; use `AD_SET` for insight reports
- **statuses** + **entity_status_type** (optional; use `AD_SET` for insight reports)

**Insight report guardrails:**
- Insight reports support one `entity_ids` value at a time, and it must be an ad set ID.
- Always send `entity_ids_type=AD_SET` when `entity_ids` is present. Do not use `CAMPAIGN`.
- Do not send `entity_type` on insight reports; `entity_type=AD_SET` does not substitute for `entity_ids_type=AD_SET`.
- Do not send `report_start`, `report_end`, `granularity`, or `limit`; insight reports are LIFETIME only.
- Use only the listed `insight_dimension` values. Do not use `LOCATION`, `GEO`, `DMA`, `STATE`, `ZIP`, `POSTAL`, `POSTAL_CODE`, `MARKET`, `DEVICE`, `OS`, `ARTIST`, `AGE_RANGE`, or `CITY_NAME`.
- For geo breakdowns, map user language to valid dimensions: country -> `COUNTRY`, region/state -> `REGION`, metro/DMA -> `METRO`, city -> `CITY`.

```bash
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-create`
Create an async CSV report for download.

Prompt for:
- **name** (2-120 chars, only alphanumeric, underscore, hyphen)
- **granularity** (DAY or LIFETIME)
- **dimensions** — What to group by:
  - AD_ACCOUNT_NAME, CAMPAIGN_NAME, CAMPAIGN_STATUS, CAMPAIGN_OBJECTIVE
  - AD_SET_NAME, AD_SET_STATUS, AD_SET_BUDGET, AD_SET_COST_MODEL
  - AD_NAME
- **metrics** — What to measure:
  - IMPRESSIONS_ON_SPOTIFY, IMPRESSIONS_OFF_SPOTIFY, SPEND, CLICKS
  - REACH, FREQUENCY, LISTENERS, NEW_LISTENERS, STREAMS
  - AD_COMPLETES, CTR, CPM, COMPLETION_RATE
- **report_start** (required if granularity=DAY)
- **report_end** (optional)
- **campaign_ids** (optional — filter to specific campaigns)
- **statuses** (optional, default: [ACTIVE])
- **insight_dimension** (optional) — Break down the report by a delivery insight dimension: `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:**
- Async report `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.
- Use request fields `dimensions` and `metrics`, not `groupBy`, `fields`, `dateRange`, or `entityType`.
- If `granularity=DAY`, include `report_start`; use UTC midnight timestamps for date boundaries.

```bash
curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST -H "Authori