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

import requests

url = "https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/breakdown"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/breakdown', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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": "11dFghVXANMlKmJXsNCbNl",
        "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, videos:write) enforced by the backend.

Deprecated, retiring 2026-08-17 — migrate to Authorization: Bearer sk_... (see apiKeyBearerAuth) before then.

Path Parameters

campaignId

string

required

Campaign identifier (UUID)

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

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

import requests

url = "https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/breakdown"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/breakdown', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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": "11dFghVXANMlKmJXsNCbNl",
        "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"
  }
}

System

Campaigns

Metrics

Videos

Campaign metrics breakdown

Authorizations

Path Parameters

Query Parameters

Response