Metrics

Soundlink metrics breakdown

Per-day metrics broken down by country. One row per (report_date, soundlink_id, country_code). Can be large, so results are paginated.

Row schema: soundlink_country_daily v1.0 — the same schema used in JSONL bulk exports. Rows are idempotent on the primary key (provider, account_id, report_date, soundlink_id, country_code); re-ingesting is safe.

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. Re-fetch or re-ingest accordingly.

Rows contain no financial fields: ads for self-serve soundlinks run in your own Meta account, so spend is not visible to Soundlink.

Maps to the Countries tab in the Soundlink Insights UI. Sum country rows for a report_date to reconstruct the day total.

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

GET

soundlinks

{soundlinkId}

metrics

breakdown

Soundlink metrics breakdown

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

import requests

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

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/breakdown', 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,
        "country_code": "US",
        "views": 4821,
        "link_clicks": 890,
        "streams": 203,
        "listeners": 145,
        "new_listeners": 120,
        "returning_listeners": 25,
        "new_listener_streams": 160,
        "returning_listener_streams": 43,
        "followers": 12,
        "streams_per_listener": 1.4,
        "ctr_lp": 0.185
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalCount": 340,
      "totalPages": 7
    }
  },
  "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) for soundlink overview and breakdown. Defaults to the soundlink creation date when omitted.

endDate

string<date>

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

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,

country_code

sortOrder

enum<string>

default:desc

Sort direction

Available options:

asc,

desc

Response

Paginated per-day country rows (soundlink_country_daily schema)

data

object

required

Show child attributes

meta

object

required

Show child attributes

Soundlink metrics breakdown

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

import requests

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

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/breakdown', 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,
        "country_code": "US",
        "views": 4821,
        "link_clicks": 890,
        "streams": 203,
        "listeners": 145,
        "new_listeners": 120,
        "returning_listeners": 25,
        "new_listener_streams": 160,
        "returning_listener_streams": 43,
        "followers": 12,
        "streams_per_listener": 1.4,
        "ctr_lp": 0.185
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalCount": 340,
      "totalPages": 7
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

System

Campaigns

Soundlinks

Videos

Soundlink metrics breakdown

Authorizations

Path Parameters

Query Parameters

Response