Metrics

Soundlink engagement breakdown

Per-day, per-track engagement metrics for a soundlink. One row per (report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id). Results are paginated.

Row schema: soundlink_engagement_daily v1.0 — the same schema used in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting is safe.

Key difference from /metrics/breakdown: breakdown aggregates views, streams, and listeners by country (soundlink_country_daily); 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 promoted-track plays) on track soundlinks.
playlist — per-track performance inside the promoted playlist on playlist soundlinks.

listeners is deduplicated within each row only. Do not sum listeners across days to get a soundlink total.

Date range: if you omit both dates, defaults to the last 90 days ending today. Override with startDate / endDate. Responses are capped at 90 days — a wider range returns 400 invalid_query_parameter.

Mutability window: rows for a given report_date can be revised for up to 7 days after the date closes due to delayed Spotify playback events.

Requires the soundlinks:read scope. Accepts API key or OAuth Bearer.

GET

soundlinks

{soundlinkId}

metrics

engagement

Soundlink engagement breakdown

curl --request GET \
  --url https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/engagement \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/engagement"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/engagement', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "schemaVersion": "1.0",
    "items": [
      {
        "provider": "soundlink",
        "account_id": "a7ac3173-2f71-4e79-921f-d15d7112dd11",
        "schema_version": "1.0",
        "report_date": "2026-08-01",
        "report_date_timezone": "UTC",
        "exported_at": "2026-08-28T03:00:00Z",
        "soundlink_id": "V1StGXR8_Z5jdHi6B-myT",
        "soundlink_name": "Midnight Drive",
        "soundlink_target_type": "track",
        "soundlink_target_isrc": "DEXW62500259",
        "soundlink_target_spotify_track_id": "11dFghVXANMlKmJXsNCbNl",
        "soundlink_target_playlist_id": null,
        "engagement_context": "catalog",
        "country_code": "US",
        "engaged_track_isrc": "DEXW62500001",
        "engaged_spotify_track_id": "4cOdK2wGLETKBW3PvgPWqT",
        "engaged_track_name": "Till The Sunrise",
        "playlist_position": null,
        "new_listeners": 42,
        "returning_listeners": 18,
        "listeners": 60,
        "new_listener_streams": 58,
        "returning_listener_streams": 31,
        "streams": 89,
        "spl": 1.48
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalCount": 120,
      "totalPages": 3
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Authorizations

Authorization

string

header

required

Pass your Soundlink sk_* API key as a Bearer token: Authorization: Bearer sk_<prefix>_<token> (not an OAuth token; see oauthBearer for that). Accepted on all Public API operations. Send only one Authorization header per request.

Path Parameters

soundlinkId

string

required

Soundlink identifier (URL-safe string, same ID used in the public sndl.ink URL)

Query Parameters

startDate

string<date>

Inclusive start date (YYYY-MM-DD). When omitted, the default depends on the endpoint: campaign overview and paginated breakdown use the campaign start date; engagement and JSONL export endpoints use the last 90 days ending today (see each operation).

endDate

string<date>

Inclusive end date (YYYY-MM-DD). Defaults to today.

engagementContext

enum<string>

Filter to a single engagement context. Omit to return both.

Available options:

catalog,

playlist

page

integer

default:1

Page number (1-indexed)

Required range: x >= 1

pageSize

integer

default:50

Rows per page (max 500; higher default than list endpoints)

Required range: 1 <= x <= 500

sortBy

enum<string>

default:report_date

Available options:

report_date

sortOrder

enum<string>

default:desc

Sort direction

Available options:

asc,

desc

Response

Paginated engagement rows (soundlink_engagement_daily schema)

data

object

required

Show child attributes

meta

object

required

Show child attributes

Soundlink engagement breakdown

curl --request GET \
  --url https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/engagement \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/engagement"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/engagement', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "schemaVersion": "1.0",
    "items": [
      {
        "provider": "soundlink",
        "account_id": "a7ac3173-2f71-4e79-921f-d15d7112dd11",
        "schema_version": "1.0",
        "report_date": "2026-08-01",
        "report_date_timezone": "UTC",
        "exported_at": "2026-08-28T03:00:00Z",
        "soundlink_id": "V1StGXR8_Z5jdHi6B-myT",
        "soundlink_name": "Midnight Drive",
        "soundlink_target_type": "track",
        "soundlink_target_isrc": "DEXW62500259",
        "soundlink_target_spotify_track_id": "11dFghVXANMlKmJXsNCbNl",
        "soundlink_target_playlist_id": null,
        "engagement_context": "catalog",
        "country_code": "US",
        "engaged_track_isrc": "DEXW62500001",
        "engaged_spotify_track_id": "4cOdK2wGLETKBW3PvgPWqT",
        "engaged_track_name": "Till The Sunrise",
        "playlist_position": null,
        "new_listeners": 42,
        "returning_listeners": 18,
        "listeners": 60,
        "new_listener_streams": 58,
        "returning_listener_streams": 31,
        "streams": 89,
        "spl": 1.48
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalCount": 120,
      "totalPages": 3
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

System

Campaigns

Soundlinks

Videos

Soundlink engagement breakdown

Authorizations

Path Parameters

Query Parameters

Response