Metrics

Soundlink engagement export (JSONL)

Streams the full engagement dataset for a soundlink as newline-delimited JSON (JSONL). Every line is a complete, valid JSON object conforming to the soundlink_engagement_daily v1.0 schema — identical to the rows returned by GET /metrics/engagement 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/engagement/export
Accept: application/x-ndjson

Response body (one JSON object per line, no trailing comma):

{"provider":"soundlink","report_date":"2026-08-01","streams":89,...}
{"provider":"soundlink","report_date":"2026-08-02","streams":104,...}

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

engagement

export

Soundlink engagement export (JSONL)

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

import requests

url = "https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/engagement/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/engagement/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,\"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}\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\":\"playlist\",\"soundlink_target_isrc\":null,\"soundlink_target_spotify_track_id\":null,\"soundlink_target_playlist_id\":\"37i9dQZF1Epwit2GR54N9P\",\"engagement_context\":\"playlist\",\"country_code\":\"DE\",\"engaged_track_isrc\":\"DEXW62500001\",\"engaged_spotify_track_id\":\"4cOdK2wGLETKBW3PvgPWqT\",\"engaged_track_name\":\"Till The Sunrise\",\"playlist_position\":14,\"new_listeners\":19,\"returning_listeners\":7,\"listeners\":26,\"new_listener_streams\":24,\"returning_listener_streams\":11,\"streams\":35,\"spl\":1.35}\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.

engagementContext

enum<string>

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

Available options:

catalog,

playlist

Response

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

One row of the soundlink_engagement_daily v1.0 schema. Primary key: (provider, account_id, report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id). 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. No status field: soundlinks do not store per-day lifecycle history. 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 string. 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). Rows can change for up to 7 days after close.

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

engagement_context

enum<string>

required

Which section this row belongs to. catalog: plays of the promoted track and same-artist catalog tracks (track soundlinks). playlist: per-track performance inside the promoted playlist (playlist soundlinks).

Available options:

catalog,

playlist

country_code

string

required

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

Example:

"US"

engaged_spotify_track_id

string

required

Spotify track ID of the engaged track. Part of the primary key.

Example:

"4cOdK2wGLETKBW3PvgPWqT"

engaged_track_name

string

required

Display name of the engaged track.

new_listeners

integer

required

Unique listeners whose first play of this track via this soundlink occurred on report_date.

Required range: x >= 0

returning_listeners

integer

required

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

Required range: x >= 0

listeners

integer

required

Total unique listeners on report_date: new_listeners + returning_listeners. Do not sum across days — the same listener can appear on multiple report_date rows.

Required range: x >= 0

new_listener_streams

integer

required

Stream count from new listeners on report_date.

Required range: x >= 0

returning_listener_streams

integer

required

Stream count from returning listeners on report_date.

Required range: x >= 0

streams

integer

required

Total streams on report_date: new_listener_streams + returning_listener_streams. Safe to sum within a day; summing across days counts repeat listens.

Required range: x >= 0

spl

number

required

Streams per listener (streams / listeners). 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.

engaged_track_isrc

string | null

ISRC of the track that received listens. May differ from soundlink_target_isrc for catalog spillover rows. null if ISRC could not be resolved.

playlist_position

integer | null

1-based slot of the engaged track on the promoted playlist for report_date (1 = top). Populated only when engagement_context = playlist. Treat null as unavailable, not an error.

Required range: x >= 1

Soundlink engagement export (JSONL)

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

import requests

url = "https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/engagement/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/engagement/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,\"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}\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\":\"playlist\",\"soundlink_target_isrc\":null,\"soundlink_target_spotify_track_id\":null,\"soundlink_target_playlist_id\":\"37i9dQZF1Epwit2GR54N9P\",\"engagement_context\":\"playlist\",\"country_code\":\"DE\",\"engaged_track_isrc\":\"DEXW62500001\",\"engaged_spotify_track_id\":\"4cOdK2wGLETKBW3PvgPWqT\",\"engaged_track_name\":\"Till The Sunrise\",\"playlist_position\":14,\"new_listeners\":19,\"returning_listeners\":7,\"listeners\":26,\"new_listener_streams\":24,\"returning_listener_streams\":11,\"streams\":35,\"spl\":1.35}\n"

System

Campaigns

Soundlinks

Videos

Soundlink engagement export (JSONL)

Authorizations

Path Parameters

Query Parameters

Response