Skip to main content
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. Requires soundlinks:read. Use a soundlinkId from Syncing soundlinks. Soundlink metrics omit spend, fees, and efficiency fields (cpl, cpf) — ads run in your Meta account. 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.

​
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 or engagement rows for new_listeners, returning_listeners, and the stream splits.

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

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

​
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 — 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 · Syncing soundlinks · JSONL exports · Campaign metrics · API Reference