JSONL exports

Export endpoints stream newline-delimited JSON (JSONL). Each line is one complete JSON object — load directly into BigQuery, Snowflake, or any JSONL-aware tool without cursor logic.

Endpoints

Export	Path
Country breakdown	`GET /v1/campaigns/{campaignId}/metrics/breakdown/export`
Track engagement	`GET /v1/campaigns/{campaignId}/metrics/engagement/export`

Requires the metrics:read scope.

Request

curl -sS \
  'https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/breakdown/export?startDate=2026-04-01&endDate=2026-04-30' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET' \
  -H 'Accept: application/x-ndjson'

Optional query params:

startDate, endDate — inclusive YYYY-MM-DD
engagementContext — catalog or playlist (engagement export only)

Date windows

Responses are capped at 90 days per request. If you omit both dates, the API uses a default window of the last 90 days ending today. For longer campaign histories, page in 90-day slices:

2026-01-01 → 2026-03-31
2026-04-01 → 2026-06-30
...

If endDate is before startDate, or the range exceeds 90 days, you get 400 with invalid_date_range or invalid_query_parameter.

Response headers

Header	Purpose
`Content-Type: application/x-ndjson`	One JSON object per line
`Content-Disposition`	Suggested filename, e.g. `breakdown_{id}_{start}_{end}.jsonl`
`X-Row-Count`	Total lines in the response (progress tracking)

Ingest pattern

import json
import requests

resp = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, stream=True)
for line in resp.iter_lines():
    if line:
        row = json.loads(line)
        # upsert on primary key from row schema

Node.js users can stream the same exports with the TypeScript SDK (for await over metrics.breakdown.export). Treat each line as an upsert on the schema primary key (documented in Understanding metrics). Re-running the same window after the 7-day mutability period is safe.

Paginated vs export

	Paginated (`/metrics/breakdown`)	Export (`/metrics/.../export`)
Format	JSON envelope + `pagination`	Raw JSONL stream
Max rows per call	`pageSize` up to 500	Full window (≤ 90 days)
Best for	UI, small probes	Warehouses, scheduled jobs

Understanding metrics · Playlist position · Errors

Get started

For Developers

Learn

Endpoints

Request

Date windows

Response headers

Ingest pattern

Paginated vs export

Next

​Endpoints

​Request

​Date windows

​Response headers

​Ingest pattern

​Paginated vs export

​Next

Endpoints

Request

Date windows

Response headers

Ingest pattern

Paginated vs export

Next