> ## Documentation Index
> Fetch the complete documentation index at: https://www.getsoundlink.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding metrics

> When to use overview, breakdown, and engagement endpoints.

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](#breakdown-by-country) 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.

| Use case                           | Endpoint              |
| ---------------------------------- | --------------------- |
| Interactive sync, small windows    | Paginated `breakdown` |
| Full backfill, pipelines, BigQuery | `breakdown/export`    |

## 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](/docs/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](/docs/playlist-position) · [JSONL exports](/docs/jsonl-exports) · [API Reference](/docs/api-reference)