Campaign engagement export (JSONL)
Streams the full engagement dataset for a campaign as
newline-delimited JSON (JSONL). Every line is a complete, valid
JSON object conforming to the campaign_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/campaigns/{campaignId}/metrics/engagement/export with header Accept: application/x-ndjson.
Response body (one JSON object per line, no trailing comma), for example:
{"provider":"soundlink","report_date":"2026-04-01","streams":89,...}{"provider":"soundlink","report_date":"2026-04-02","streams":104,...}
Date range: defaults to the full campaign lifetime plus 30 days
post-end to capture tail engagement. Override with startDate /
endDate. Responses are capped at 90 days — if the requested
range exceeds 90 days, the most recent 90 days are returned. Use
startDate / endDate to page through longer windows in 90-day
slices.
Mutability: same 7-day revision window as the paginated endpoint. Re-fetching and re-ingesting on the primary key is safe (idempotent).
Authorizations
Pass your Soundlink sk_* API key in the x-api-key header.
Keys can carry explicit scopes (for example campaigns:read, metrics:read) enforced by the backend.
Path Parameters
Campaign identifier (e.g. camp_abc123)
Query Parameters
Inclusive start date (YYYY-MM-DD). Defaults to campaign start date.
Inclusive end date (YYYY-MM-DD). Defaults to today.
Filter to a single engagement context. Omit to return both.
catalog, playlist Response
JSONL stream. Each line is a campaign_engagement_daily v1.0 row.
Lines are sorted by (report_date asc, engagement_context, country_code, engaged_spotify_track_id).
One row of the campaign_engagement_daily v1.0 schema.
Primary key: (provider, account_id, report_date, campaign_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.
Always soundlink. Identifies the data provider for multi-source warehouses.
soundlink Soundlink organization ID (UUID).
Schema version string. Pin your ingest pipeline to this value.
"1.0"
UTC calendar date the metrics belong to (YYYY-MM-DD). Rows can change for up to 7 days after close.
Always UTC.
UTC ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same report_date is re-delivered.
Soundlink campaign UUID. Stable for the lifetime of the campaign.
Human-readable campaign name.
Whether this campaign promotes a track or a playlist. null if undetermined.
track, playlist Campaign lifecycle status on report_date.
active = campaign was running; ended = campaign had ended or was refunded;
scheduled = report_date is before campaign start.
Post-campaign rows will have status = ended.
active, ended, scheduled Which dashboard section the row maps to.
catalog = same-artist spillover (and direct promoted-track plays) on track campaigns.
playlist = per-track performance inside the promoted playlist on playlist campaigns.
catalog, playlist ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
"US"
Stable track identifier used in the primary key. Currently this is the Spotify track ID for the engaged track.
"4cOdK2wGLETKBW3PvgPWqT"
Display name of the engaged track.
Unique listeners whose first play of this track on this smart link occurred on report_date.
x >= 0Unique listeners who played this track on report_date but whose first play was on an earlier date.
x >= 0Total unique listeners on report_date: new_listeners + returning_listeners.
Do not sum across days — the same listener can appear on multiple report_date rows.
x >= 0Stream count from new listeners on report_date.
x >= 0Stream count from returning listeners on report_date.
x >= 0Total streams on report_date: new_listener_streams + returning_listener_streams.
Safe to sum within a day; summing across days counts repeat listens.
x >= 0Streams per listener (streams / listeners). Zero if listeners is zero.
ISRC of the promoted track. Populated when campaign_target_type = track; otherwise null.
Spotify track ID of the promoted track. Populated when campaign_target_type = track; otherwise null.
Spotify playlist ID. Populated when campaign_target_type = playlist; otherwise null.
ISRC of the track that received listens. May differ from campaign_target_isrc
for catalog spillover rows. null if ISRC could not be resolved.
1-based slot index of the engaged track in the promoted playlist on report_date.
Populated for engagement_context = playlist when playlist snapshot data is available.
null for catalog rows and until position data is delivered (reserved for future delivery in v1.0).
x >= 1