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.
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
Accept: application/x-ndjson
Response body (one JSON object per line, no trailing comma):
{"provider":"soundlink","report_date":"2026-04-01","streams":89,...}
{"provider":"soundlink","report_date":"2026-04-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).
Authorizations
Pass your Soundlink sk_* API key in the x-api-key header.
Keys can carry explicit scopes (for example campaigns:read, metrics:read, videos:write) enforced by the backend.
Deprecated, retiring 2026-08-17 — migrate to Authorization: Bearer sk_... (see apiKeyBearerAuth) before then.
Path Parameters
Campaign identifier (UUID)
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 of the engaged track on the promoted playlist for report_date (1 = top).
Populated only when engagement_context = playlist and that day's playlist crawl listed the track.
null for catalog rows; before the day's crawl completes (current UTC day is often null until later morning UTC);
when the track was not listed or could not be matched to that day's crawl; or while historical backfill is still catching up.
Field is beta until historical backfill finishes. Treat null as unavailable — not an error.
x >= 1