Metrics

Campaign engagement breakdown

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

GET

campaigns

{campaignId}

metrics

engagement

Campaign engagement breakdown

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

{
  "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": 210,
      "totalPages": 5
    }
  },
  "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.

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,

streams,

listeners

sortOrder

enum<string>

default:desc

Sort direction

Available options:

asc,

desc

Response

Paginated per-day per-track engagement rows (campaign_engagement_daily schema)

data

object

required

Show child attributes

meta

object

required

Show child attributes

Campaign engagement export (JSONL)Streams the full engagement dataset for a campaign as **newline-delimited JSON (JSONL)**. Every line is a complete, valid JSON object conforming to the `campaign_engagement_daily` v1.0 schema — identical to the rows returned by `GET /metrics/engagement` 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/engagement/export` with header `Accept: application/x-ndjson`. **Response body (one JSON object per line, no trailing comma), for example:** - `{"provider":"soundlink","report_date":"2026-04-01","streams":89,...}` - `{"provider":"soundlink","report_date":"2026-04-02","streams":104,...}` **Date range:** defaults to the full campaign lifetime plus 30 days post-end to capture tail engagement. Override with `startDate` / `endDate`. **Responses are capped at 90 days** — if the requested range exceeds 90 days, the most recent 90 days are returned. Use `startDate` / `endDate` to page through longer windows in 90-day slices. **Mutability:** same 7-day revision window as the paginated endpoint. Re-fetching and re-ingesting on the primary key is safe (idempotent).

Campaign engagement breakdown

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

{
  "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": 210,
      "totalPages": 5
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}