Skip to main content
GET
Soundlink engagement export (JSONL)

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