Metrics

Soundlink metrics breakdown export (JSONL)

Streams the full country-level metrics dataset for a soundlink as newline-delimited JSON (JSONL). Every line is a complete, valid JSON object conforming to the soundlink_country_daily v1.0 schema — identical to the rows returned by GET /metrics/breakdown but without pagination or an envelope wrapper.

Designed for data pipeline consumers: load directly into BigQuery, Snowflake, or any JSONL-aware ingest tool without cursor logic.

Usage:

GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export
Accept: application/x-ndjson

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. Page longer histories in 90-day slices.

Mutability: 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-fetching and re-ingesting on the primary key is safe (idempotent).

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

GET

soundlinks

{soundlinkId}

metrics

breakdown

export

Soundlink metrics breakdown export (JSONL)

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

import requests

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

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/export', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

"{\"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,\"spotify_link_clicks\":820,\"apple_music_link_clicks\":50,\"youtube_music_link_clicks\":10,\"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}\n{\"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\":\"DE\",\"views\":2103,\"link_clicks\":31,\"spotify_link_clicks\":28,\"apple_music_link_clicks\":2,\"youtube_music_link_clicks\":0,\"streams\":87,\"listeners\":61,\"new_listeners\":48,\"returning_listeners\":13,\"new_listener_streams\":64,\"returning_listener_streams\":23,\"followers\":4,\"streams_per_listener\":1.43,\"ctr_lp\":0.0147}\n"

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.

Response

JSONL stream. Each line is a soundlink_country_daily v1.0 row. Lines are sorted by (report_date asc, country_code).

One row of the soundlink_country_daily v1.0 schema. Primary key: (provider, account_id, report_date, soundlink_id, country_code). Rows are idempotent — re-ingesting on the primary key is safe. Values for a given report_date may be revised for up to 7 days after the date closes due to delayed Spotify playback events. Rows contain no financial fields.

provider

enum<string>

required

Always soundlink. Identifies the data provider for multi-source warehouses.

Available options:

soundlink

account_id

string

required

Soundlink organization ID (UUID).

schema_version

string

required

Schema version. Pin your ingest pipeline to this value.

Example:

"1.0"

report_date

string<date>

required

UTC calendar date the metrics belong to (YYYY-MM-DD).

report_date_timezone

enum<string>

required

Always UTC.

Available options:

UTC

exported_at

string<date-time>

required

ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same report_date is re-delivered.

soundlink_id

string

required

Unique ID of this soundlink.

Example:

"V1StGXR8_Z5jdHi6B-myT"

soundlink_name

string

required

Human-readable soundlink name.

soundlink_target_type

enum<string> | null

required

Whether this soundlink promotes a track or playlist. null if undetermined.

Available options:

track,

playlist

country_code

string

required

ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.

views

integer

required

Soundlink landing page views in this country on this day.

spotify_link_clicks

integer

required

Continue sessions to Spotify from the landing page. Safe to sum across countries and days.

apple_music_link_clicks

integer

required

Continue sessions to Apple Music from the landing page (outbound click only; no Apple Music playback attribution). Safe to sum across countries and days.

youtube_music_link_clicks

integer

required

Continue sessions to YouTube Music from the landing page (outbound click only; no YouTube Music playback attribution). Often 0 on standalone soundlink marts. Safe to sum across countries and days.

streams

integer

required

Spotify streams attributed to this soundlink in this country on this day: new_listener_streams + returning_listener_streams. Observed Spotify-side events, not modelled estimates. Safe to sum within a day; summing across days counts repeat listens.

listeners

integer

required

Unique Spotify listeners attributed to this soundlink in this country on this day: new_listeners + returning_listeners. Do not sum across days — the same listener can appear on multiple report_date rows.

followers

integer

required

Spotify artist follower gains attributed to this soundlink in this country on this day.

streams_per_listener

number

required

streams / listeners for this row. Zero if listeners is zero.

soundlink_target_isrc

string | null

ISRC of the promoted track. Populated when soundlink_target_type = track; otherwise null.

soundlink_target_spotify_track_id

string | null

Spotify track ID of the promoted track. Populated when soundlink_target_type = track; otherwise null.

soundlink_target_playlist_id

string | null

Spotify playlist ID. Populated when soundlink_target_type = playlist; otherwise null.

link_clicks

integer | null

CTA clicks across all DSPs on the landing page (including DSPs without a dedicated column). Always >= the sum of spotify_link_clicks + apple_music_link_clicks + youtube_music_link_clicks — do not derive a per-DSP count by subtraction. Null if not tracked for this soundlink type.

new_listeners

integer | null

Unique listeners whose first play via this soundlink occurred on report_date in this country.

returning_listeners

integer | null

Unique listeners who played on report_date in this country but whose first play was on an earlier date.

new_listener_streams

integer | null

Stream count from new listeners on report_date in this country.

returning_listener_streams

integer | null

Stream count from returning listeners on report_date in this country.

ctr_lp

number | null

Landing page click-through rate (link_clicks / views). Computed against landing page views, not ad impressions — do not combine with ctr_linkclick from campaign_country_daily. Null if views is zero or link_clicks is null.

Soundlink metrics breakdown export (JSONL)

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

import requests

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

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/export', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

"{\"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,\"spotify_link_clicks\":820,\"apple_music_link_clicks\":50,\"youtube_music_link_clicks\":10,\"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}\n{\"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\":\"DE\",\"views\":2103,\"link_clicks\":31,\"spotify_link_clicks\":28,\"apple_music_link_clicks\":2,\"youtube_music_link_clicks\":0,\"streams\":87,\"listeners\":61,\"new_listeners\":48,\"returning_listeners\":13,\"new_listener_streams\":64,\"returning_listener_streams\":23,\"followers\":4,\"streams_per_listener\":1.43,\"ctr_lp\":0.0147}\n"

System

Wallet

Campaigns

Soundlinks

Videos

Pixels

Soundlink metrics breakdown export (JSONL)

Authorizations

Path Parameters

Query Parameters

Response