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

# Soundlink metrics

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

Three layers of soundlink performance for soundlinks **without** a campaign. Pick the endpoint that matches how you store and report the data.

For paid campaigns, see [Campaign metrics](/docs/understanding-metrics).

Requires `soundlinks:read`. Use a `soundlinkId` from [Syncing soundlinks](/docs/soundlinks).

Soundlink metrics omit spend, fees, and efficiency fields (`cpl`, `cpf`) — ads run in your Meta account.

| Use               | Endpoint                            | Maps to Insights             |
| ----------------- | ----------------------------------- | ---------------------------- |
| Period totals     | `/metrics/overview`                 | **Overview**                 |
| Per-day × country | `/metrics/breakdown` (+ `/export`)  | **Countries**                |
| Per-day × track   | `/metrics/engagement` (+ `/export`) | Catalog / playlist spillover |

`startDate` and `endDate` are inclusive (`YYYY-MM-DD`).

* **Overview** and paginated **breakdown:** default to the soundlink creation date → today (no 90-day cap).
* **Engagement** (paginated + export) and **breakdown export:** default to the last 90 days ending today; responses are capped at **90 days** per request. Page longer histories in 90-day slices. See [JSONL exports](/docs/jsonl-exports).

## Overview

`GET /v1/soundlinks/{soundlinkId}/metrics/overview`

Soundlink-level totals for a date range: `views`, `link_clicks` (nullable), `streams`, `listeners`, `followers`, `streams_per_listener`, and `ctr_lp`. One payload per request window — not broken down by country or track.

`listeners` is the sum of daily per-country `new_listeners` (not period-unique across days or countries). It is **not** equal to summing breakdown `listeners` (new + returning).

**New and returning splits are not on overview.** Use [breakdown](#breakdown-by-country) or [engagement](#engagement-by-track) rows for `new_listeners`, `returning_listeners`, and the stream splits.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS 'https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/overview?startDate=2026-08-01&endDate=2026-08-31' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET'
```

## Breakdown (by country)

`GET /v1/soundlinks/{soundlinkId}/metrics/breakdown` (paginated)

`GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export` (JSONL)

Per-day, per-country rows (`soundlink_country_daily` v1.0). Primary key:

`(provider, account_id, report_date, soundlink_id, country_code)`

On track soundlinks (`soundlink_target_type = track`), each row also includes `soundlink_target_isrc` and `soundlink_target_spotify_track_id`.

Maps to the **Countries** tab in Soundlink Insights. Use for geo reporting and daily warehouse loads by territory. Summing country rows for a given `report_date` reconstructs the day total across territories.

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS 'https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/breakdown?startDate=2026-08-01&endDate=2026-08-31&page=1&pageSize=50' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET'
```

## Engagement (by track)

`GET /v1/soundlinks/{soundlinkId}/metrics/engagement` (paginated)

`GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export` (JSONL)

Per-day, per-track rows (`soundlink_engagement_daily` v1.0). Primary key:

`(provider, account_id, report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`

**Key difference from breakdown:** breakdown aggregates views, streams, and listeners by **country**; engagement breaks down **which tracks** listeners played, including catalog spillover and playlist slot performance (`engagement_context`, `engaged_spotify_track_id`).

**`engagement_context` values:**

* `catalog` — same-artist spillover and direct plays on track soundlinks
* `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` when available — the track's 1-based slot on the soundlink playlist for that `report_date`.

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS 'https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/engagement?startDate=2026-08-01&endDate=2026-08-31&page=1&pageSize=50' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET'
```

## Data mutability

Rows for a given `report_date` can change for up to **7 days** after the date closes (delayed Spotify events). Re-fetch and re-ingest on the primary key — it is idempotent.

## Listeners vs streams

On breakdown and 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.

## Typical sync flow

1. **Daily:** [list soundlinks](/docs/soundlinks) — upsert catalog
2. **Daily:** overview and/or breakdown (paginated or export)
3. **Optional:** engagement (paginated or export) for track-level spillover

Your organization is determined only from the API key (or OAuth token). You never pass an organization id in query params. Warehouse rows use `account_id` for the same organization UUID that catalog JSON calls `organizationId`. Join on `soundlink_id`.

## FAQ

**Where are new / returning listeners?** On `breakdown` and `engagement` rows (`new_listeners`, `returning_listeners`, and the stream splits). Overview only exposes aggregated `listeners` (sum of daily per-country `new_listeners`).

**How do I get one row per day without country?** Sum that day's breakdown rows across `country_code`, or store the country rows and aggregate in your warehouse.

## Next

[Warehouse connector](/docs/warehouse-connector) · [Syncing soundlinks](/docs/soundlinks) · [JSONL exports](/docs/jsonl-exports) · [Campaign metrics](/docs/understanding-metrics) · [API Reference](/docs/api-reference)