Overview
GET /v1/campaigns/{campaignId}/metrics/overview
Campaign-level totals for a date range: spend, streams, listeners, followers, and efficiency metrics (CPL, CPF, CTR). One row per campaign per request window.
Use for dashboards, executive summaries, and quick health checks. Not broken down by country or track.
Breakdown (by country)
GET /v1/campaigns/{campaignId}/metrics/breakdown (paginated)
GET /v1/campaigns/{campaignId}/metrics/breakdown/export (JSONL)
Per-day, per-country rows (campaign_country_daily v1.0). Primary key:
(provider, account_id, report_date, campaign_id, country_code)
On track campaigns (campaign_target_type = track), each row also includes campaign_target_isrc and campaign_target_spotify_track_id. Use campaign_target_spotify_track_id to join with partner track catalogs when ISRC is unavailable.
Maps to the Countries tab in Soundlink Insights. Use for geo reporting and daily warehouse loads by territory.
| Use case | Endpoint |
|---|---|
| Interactive sync, small windows | Paginated breakdown |
| Full backfill, pipelines, BigQuery | breakdown/export |
Engagement (by track)
GET /v1/campaigns/{campaignId}/metrics/engagement (paginated)
GET /v1/campaigns/{campaignId}/metrics/engagement/export (JSONL)
Per-day, per-track rows (campaign_engagement_daily v1.0). Primary key:
(provider, account_id, report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)
Engagement rows also include campaign_target_isrc and campaign_target_spotify_track_id for the promoted track when campaign_target_type = track.
engagement_context values:
catalog— same-artist spillover and direct plays on track campaignsplaylist— per-track performance inside the promoted playlist
?engagementContext=catalog or playlist when you only need one slice.
Data mutability
Rows for a givenreport_date can change for up to 7 days after the date closes (delayed Meta and Spotify events). Re-fetch and re-ingest on the primary key — it is idempotent.
Listeners vs streams
On engagement rows, do not sumlisteners across days — the same listener can appear on multiple report_date rows. Summing streams within a day is safe; across days it counts repeat listens.