Overview
GET /v1/campaigns/{campaignId}/metrics/overview
Campaign-level totals for a date range: listeners, streams, followers, delivery (impressions, ad_clicks, link_clicks), spend (spend_media, spend_total, fees), and efficiency metrics (cpl, cpf, streams_per_listener). One row per campaign per request window.
Use for dashboards, executive summaries, and quick health checks. Not broken down by country or track. CTR fields (ctr_linkclick, ctr_adclick) are on breakdown rows, not overview.
New and returning splits are not on overview. Use breakdown or engagement rows for new_listeners, returning_listeners, and the stream splits.
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.
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 counts plays from listeners who connected Spotify through the campaign’s soundlink, starting when they connected. Use it for catalog spillover and playlist performance while the campaign runs.
Listening history is synced while the campaign is active. After it ends, sync stops for listeners whose only connection is that campaign, so post-campaign days are partial and usually drop sharply — do not read that drop as listeners leaving.
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.
Playlist engagement rows include playlist_position — the track’s 1-based slot on the campaign playlist for that report_date. See Playlist position.
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 breakdown and 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.