Metrics

Campaign engagement breakdown

Per-day, per-track engagement metrics for a campaign. One row per (report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id). Results are paginated.

Row schema: campaign_engagement_daily v1.0 — the same schema used in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting is safe.

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.

engagement_context values:

catalog — same-artist spillover (and direct promoted-track plays) on track campaigns.
playlist — per-track performance inside the promoted playlist on playlist campaigns.

listeners is deduplicated within each row only. Do not sum listeners across days to get a campaign total.

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.

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.

Requires the metrics:read scope. Accepts API key or OAuth Bearer.

GET

campaigns

{campaignId}

metrics

engagement

Campaign engagement breakdown

curl --request GET \
  --url https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/engagement \
  --header 'Authorization: Bearer <token>'

import requests

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

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/engagement', 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-d15d7112cc9a",
        "schema_version": "1.0",
        "report_date": "2026-04-08",
        "report_date_timezone": "UTC",
        "exported_at": "2026-05-22T10:12:11Z",
        "campaign_id": "8ccd7b88-2591-4b94-848f-f142f5c6bba1",
        "campaign_name": "9 To 5",
        "campaign_target_type": "track",
        "campaign_target_isrc": "DEXW62500272",
        "campaign_target_spotify_track_id": "2RkZ5WPkKyBf0u8vN3dNgb",
        "campaign_target_playlist_id": null,
        "status": "ended",
        "engagement_context": "catalog",
        "country_code": "US",
        "engaged_track_isrc": "DEXW62500001",
        "engaged_spotify_track_id": "4cOdK2wGLETKBW3PvgPWqT",
        "engaged_track_name": "Till The Sunrise",
        "playlist_position": null,
        "new_listeners": 42,
        "returning_listeners": 18,
        "listeners": 60,
        "new_listener_streams": 58,
        "returning_listener_streams": 31,
        "streams": 89,
        "spl": 1.48
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalCount": 120,
      "totalPages": 3
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

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

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

sortOrder

enum<string>

default:desc

Sort direction

Available options:

asc,

desc

Response

Paginated engagement rows (campaign_engagement_daily schema)

data

object

required

Show child attributes

meta

object

required

Show child attributes

Campaign engagement breakdown

curl --request GET \
  --url https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/engagement \
  --header 'Authorization: Bearer <token>'

import requests

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

headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/engagement', 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-d15d7112cc9a",
        "schema_version": "1.0",
        "report_date": "2026-04-08",
        "report_date_timezone": "UTC",
        "exported_at": "2026-05-22T10:12:11Z",
        "campaign_id": "8ccd7b88-2591-4b94-848f-f142f5c6bba1",
        "campaign_name": "9 To 5",
        "campaign_target_type": "track",
        "campaign_target_isrc": "DEXW62500272",
        "campaign_target_spotify_track_id": "2RkZ5WPkKyBf0u8vN3dNgb",
        "campaign_target_playlist_id": null,
        "status": "ended",
        "engagement_context": "catalog",
        "country_code": "US",
        "engaged_track_isrc": "DEXW62500001",
        "engaged_spotify_track_id": "4cOdK2wGLETKBW3PvgPWqT",
        "engaged_track_name": "Till The Sunrise",
        "playlist_position": null,
        "new_listeners": 42,
        "returning_listeners": 18,
        "listeners": 60,
        "new_listener_streams": 58,
        "returning_listener_streams": 31,
        "streams": 89,
        "spl": 1.48
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "totalCount": 120,
      "totalPages": 3
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

System

Campaigns

Soundlinks

Videos

Campaign engagement breakdown

Authorizations

Path Parameters

Query Parameters

Response