Metrics

Campaign metrics breakdown export (JSONL)

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

Date range: defaults to the full campaign active period. Override with startDate / endDate. Responses are capped at 90 days — use startDate / endDate to slice through longer windows manually.

Mutability: rows for a given report_date can be revised for up to 7 days after the date closes due to delayed events from Meta and Spotify. Re-fetching and re-ingesting on the primary key is safe (idempotent).

GET

campaigns

{campaignId}

metrics

breakdown

export

Campaign metrics breakdown export (JSONL)

curl --request GET \
  --url https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/breakdown/export \
  --header 'x-api-key: <api-key>'

"{\"provider\":\"soundlink\",\"account_id\":\"a7ac3173-2f71-4e79-921f-d15d7112dd11\",\"schema_version\":\"1.0\",\"report_date\":\"2026-04-01\",\"report_date_timezone\":\"UTC\",\"exported_at\":\"2026-05-20T03:00:00Z\",\"campaign_id\":\"f1e28d31-c358-4284-9bef-00a2334625fd\",\"campaign_name\":\"Sleep Playlist\",\"campaign_target_type\":\"track\",\"campaign_target_isrc\":\"DEXW62500259\",\"campaign_target_spotify_track_id\":\"6habFhsOp2NvndAvgiJ01P\",\"campaign_target_playlist_id\":null,\"country_code\":\"US\",\"impressions\":4821,\"ad_clicks\":112,\"link_clicks\":89,\"streams\":203,\"listeners\":145,\"followers\":12,\"streams_per_listener\":1.4,\"spend_media\":42.50,\"spend_total\":53.13,\"fees\":10.63,\"currency\":\"USD\",\"currency_account\":\"USD\",\"cpl\":0.293,\"cpf\":3.542,\"cpc_linkclick\":0.478,\"ctr_linkclick\":0.0185,\"ctr_adclick\":0.0232,\"cost_per_result\":3.542,\"result_type\":\"follow\"}\n{\"provider\":\"soundlink\",\"account_id\":\"a7ac3173-2f71-4e79-921f-d15d7112dd11\",\"schema_version\":\"1.0\",\"report_date\":\"2026-04-01\",\"report_date_timezone\":\"UTC\",\"exported_at\":\"2026-05-20T03:00:00Z\",\"campaign_id\":\"f1e28d31-c358-4284-9bef-00a2334625fd\",\"campaign_name\":\"Sleep Playlist\",\"campaign_target_type\":\"track\",\"campaign_target_isrc\":\"DEXW62500259\",\"campaign_target_spotify_track_id\":\"6habFhsOp2NvndAvgiJ01P\",\"campaign_target_playlist_id\":null,\"country_code\":\"DE\",\"impressions\":2103,\"ad_clicks\":48,\"link_clicks\":31,\"streams\":87,\"listeners\":61,\"followers\":4,\"streams_per_listener\":1.43,\"spend_media\":18.20,\"spend_total\":22.75,\"fees\":4.55,\"currency\":\"USD\",\"currency_account\":\"USD\",\"cpl\":0.298,\"cpf\":4.55,\"cpc_linkclick\":0.587,\"ctr_linkclick\":0.0148,\"ctr_adclick\":0.0228,\"cost_per_result\":4.55,\"result_type\":\"follow\"}\n"

Authorizations

x-api-key

string

header

required

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

campaignId

string

required

Campaign identifier (e.g. camp_abc123)

Query Parameters

startDate

string<date>

Inclusive start date (YYYY-MM-DD). Defaults to campaign start date.

endDate

string<date>

Inclusive end date (YYYY-MM-DD). Defaults to today.

Response

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

One row of the campaign_country_daily v1.0 schema. Primary key: (provider, account_id, report_date, campaign_id, country_code). 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 events from Meta and Spotify.

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

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 playlist. null if undetermined.

Available options:

track,

playlist

country_code

string

required

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

streams

integer

required

Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.

listeners

integer

required

Unique Spotify listeners attributed to this campaign in this country on this day (7-day click-through window). Summing country rows gives the correct campaign-level total.

followers

integer

required

Spotify artist follower gains attributed to this campaign in this country on this day (7-day click-through window).

streams_per_listener

number

required

streams / listeners for this row. Zero if listeners is zero.

spend_media

number

required

Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In currency.

spend_total

number

required

Total billed by Soundlink (spend_media + fees). Computed as spend_media / (1 - fee_pct).

fees

number

required

Soundlink service fee (spend_total - spend_media).

currency

string

required

Currency for spend fields. Currently always USD.

currency_account

string

required

Account billing currency. Currently always USD. Will differ from currency once EUR delivery is available.

cpl

number

required

Cost per listener (spend_media / listeners). Zero if listeners is zero.

cpf

number

required

Cost per follower (spend_media / followers). Zero if followers is zero.

cost_per_result

number

required

Cost per primary campaign result. Currently equivalent to cpf (cost per follower). See result_type.

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.

impressions

integer | null

Total Meta ad impressions served in this country on this day.

ad_clicks

integer | null

Total clicks on the Meta ad (all click types). Use ctr_adclick for ad-level CTR.

link_clicks

integer | null

Clicks on "Continue with Spotify" on the Soundlink landing page. Use cpc_linkclick / ctr_linkclick for outbound CPC/CTR.

cpc_linkclick

number | null

Cost per outbound click (spend_media / link_clicks). Null if link_clicks is null or zero.

ctr_linkclick

number | null

Outbound CTR (link_clicks / impressions). Null if impressions is null or zero.

ctr_adclick

number | null

Meta ad CTR (ad_clicks / impressions). Null if impressions is null or zero.

result_type

enum<string> | null

The conversion event used for cost_per_result. Currently always follow.

Available options:

lp_click,

stream,

follow

Campaign engagement breakdownPer-day, per-track engagement metrics for a campaign. One row per `(report_date, campaign_id, engagement_context, engaged_spotify_track_id)`. **Key difference from `/metrics/breakdown`:** this endpoint covers the full engagement window — including post-campaign streaming activity — not just dates when the campaign was actively running. Use this for catalog spillover analysis and long-tail retention. **`engagement_context` values:** - `catalog` — same-artist spillover (and direct promoted-track plays) on track campaigns. `engaged_track_isrc` may equal `campaign_target_isrc` (the promoted track itself) or differ (spillover tracks). - `playlist` — per-track performance inside the promoted playlist on playlist campaigns. One row per track in the playlist per day. **`listeners` is deduplicated within each row only.** Do not sum `listeners` across days to get a campaign total — the same listener can appear on multiple `report_date` rows. Row schema: `campaign_engagement_daily` v1.0. Rows are idempotent on the primary key; re-ingesting is safe. **Mutability window:** rows for a given `report_date` can be revised for up to 7 days after the date closes due to delayed Spotify playback events.

Campaign metrics breakdown export (JSONL)

curl --request GET \
  --url https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/breakdown/export \
  --header 'x-api-key: <api-key>'

"{\"provider\":\"soundlink\",\"account_id\":\"a7ac3173-2f71-4e79-921f-d15d7112dd11\",\"schema_version\":\"1.0\",\"report_date\":\"2026-04-01\",\"report_date_timezone\":\"UTC\",\"exported_at\":\"2026-05-20T03:00:00Z\",\"campaign_id\":\"f1e28d31-c358-4284-9bef-00a2334625fd\",\"campaign_name\":\"Sleep Playlist\",\"campaign_target_type\":\"track\",\"campaign_target_isrc\":\"DEXW62500259\",\"campaign_target_spotify_track_id\":\"6habFhsOp2NvndAvgiJ01P\",\"campaign_target_playlist_id\":null,\"country_code\":\"US\",\"impressions\":4821,\"ad_clicks\":112,\"link_clicks\":89,\"streams\":203,\"listeners\":145,\"followers\":12,\"streams_per_listener\":1.4,\"spend_media\":42.50,\"spend_total\":53.13,\"fees\":10.63,\"currency\":\"USD\",\"currency_account\":\"USD\",\"cpl\":0.293,\"cpf\":3.542,\"cpc_linkclick\":0.478,\"ctr_linkclick\":0.0185,\"ctr_adclick\":0.0232,\"cost_per_result\":3.542,\"result_type\":\"follow\"}\n{\"provider\":\"soundlink\",\"account_id\":\"a7ac3173-2f71-4e79-921f-d15d7112dd11\",\"schema_version\":\"1.0\",\"report_date\":\"2026-04-01\",\"report_date_timezone\":\"UTC\",\"exported_at\":\"2026-05-20T03:00:00Z\",\"campaign_id\":\"f1e28d31-c358-4284-9bef-00a2334625fd\",\"campaign_name\":\"Sleep Playlist\",\"campaign_target_type\":\"track\",\"campaign_target_isrc\":\"DEXW62500259\",\"campaign_target_spotify_track_id\":\"6habFhsOp2NvndAvgiJ01P\",\"campaign_target_playlist_id\":null,\"country_code\":\"DE\",\"impressions\":2103,\"ad_clicks\":48,\"link_clicks\":31,\"streams\":87,\"listeners\":61,\"followers\":4,\"streams_per_listener\":1.43,\"spend_media\":18.20,\"spend_total\":22.75,\"fees\":4.55,\"currency\":\"USD\",\"currency_account\":\"USD\",\"cpl\":0.298,\"cpf\":4.55,\"cpc_linkclick\":0.587,\"ctr_linkclick\":0.0148,\"ctr_adclick\":0.0228,\"cost_per_result\":4.55,\"result_type\":\"follow\"}\n"