Metrics

Campaign metrics breakdown

Per-day metrics broken down by country. One row per (report_date, campaign_id, country_code). Can be large, so results are paginated.

Row schema: campaign_country_daily v1.0 — the same schema used in JSONL bulk exports. Rows are idempotent on the primary key (provider, account_id, report_date, campaign_id, country_code); 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 events from Meta and Spotify. Re-fetch or re-ingest accordingly.

Maps to the Countries tab in the Soundlink Insights UI. Use for daily warehouse loads.

GET

campaigns

{campaignId}

metrics

breakdown

Campaign metrics breakdown

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

{
  "data": {
    "schemaVersion": "1.0",
    "items": [
      {
        "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.5,
        "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"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalCount": 340,
      "totalPages": 7
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

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.

page

integer

default:1

Page number (1-indexed)

Required range: x >= 1

pageSize

integer

default:50

Rows per page (max 500; higher default than list endpoints)

Required range: 1 <= x <= 500

sortBy

enum<string>

default:report_date

Available options:

report_date,

spend_total

sortOrder

enum<string>

default:desc

Sort direction

Available options:

asc,

desc

Response

Paginated per-day country rows (campaign_country_daily schema)

data

object

required

Show child attributes

meta

object

required

Show child attributes

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

Campaign metrics breakdown

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

{
  "data": {
    "schemaVersion": "1.0",
    "items": [
      {
        "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.5,
        "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"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalCount": 340,
      "totalPages": 7
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}