Skip to main content
The Metrics API exposes three layers of campaign performance. Pick the endpoint that matches how you plan to store and report the data.

​
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.

​
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/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 covers the full engagement window — including post-campaign streaming — not only days when the campaign was actively running. Use for catalog spillover and long-tail retention. 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 campaigns
  • playlist — per-track performance inside the promoted playlist
Filter with ?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 (beta while historical backfill finishes). See Playlist position.

​
Data mutability

Rows for a given report_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 sum listeners 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.

​
Next

Playlist position · JSONL exports · API Reference