Skip to main content
GET
Campaign 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

campaignId
string
required

Campaign identifier (UUID)

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

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.

campaign_id
string
required

Soundlink campaign UUID. Stable for the lifetime of the campaign.

campaign_name
string
required

Human-readable campaign name.

campaign_target_type
enum<string> | null
required

Whether this campaign promotes a track or a playlist. null if undetermined.

Available options:
track,
playlist
status
enum<string>
required

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.

Available options:
active,
ended,
scheduled
engagement_context
enum<string>
required

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.

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

Stable track identifier used in the primary key. Currently this is the Spotify track ID for the engaged track.

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 on this smart link 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.

campaign_target_isrc
string | null

ISRC of the promoted track. Populated when campaign_target_type = track; otherwise null.

campaign_target_spotify_track_id
string | null

Spotify track ID of the promoted track. Populated when campaign_target_type = track; otherwise null.

campaign_target_playlist_id
string | null

Spotify playlist ID. Populated when campaign_target_type = playlist; otherwise null.

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

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

Required range: x >= 1