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,\"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,\"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.

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

Clicks on "Continue with Spotify" on the landing page — outbound clicks to Spotify. 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,\"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,\"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

Campaigns

Soundlinks

Videos

Soundlink metrics breakdown export (JSONL)

Authorizations

Path Parameters

Query Parameters

Response