> ## Documentation Index > Fetch the complete documentation index at: https://www.getsoundlink.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 Accept: application/x-ndjson ``` **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`. Page longer histories in 90-day slices. **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). ## OpenAPI ````yaml /openapi/soundlink-public-api-v1.yaml get /v1/campaigns/{campaignId}/metrics/breakdown/export openapi: 3.0.3 info: title: Soundlink Public API version: 0.0.1-draft description: > Campaign listing, metrics, and write operations for Soundlink partner organizations. **Base URL:** `https://api.getsoundlink.com` **Authentication:** send a `sk_*` API key created in the Soundlink app (Settings → Developer → API keys) using one of: 1. **`Authorization: Bearer` (recommended)**: ``` Authorization: Bearer sk_abc123_ ``` 2. **`x-api-key` header (deprecated, retiring 2026-08-17)** — migrate to Bearer above before then: ``` x-api-key: sk_abc123_ ``` Sending both headers returns `401 mixed_credentials`. All responses are wrapped in a standard envelope: ```json { "data": , "meta": { "requestId": "" } } ``` Errors follow the same envelope shape with an `error` field instead of `data`. servers: - url: https://api.getsoundlink.com description: Production security: - apiKeyAuth: [] - apiKeyBearerAuth: [] tags: - name: System description: Connectivity and auth verification - name: Campaigns description: >- Campaign listing, detail, creation, and wallet management (budget, stop, tiers) - name: Metrics description: Campaign performance metrics - name: Videos description: Partner video library import for Full Control campaigns paths: /v1/campaigns/{campaignId}/metrics/breakdown/export: get: tags: - Metrics summary: Campaign metrics breakdown export (JSONL) description: > 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 Accept: application/x-ndjson ``` **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`. Page longer histories in 90-day slices. **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). operationId: exportCampaignMetricsBreakdown parameters: - $ref: '#/components/parameters/campaignId' - $ref: '#/components/parameters/startDate' - $ref: '#/components/parameters/endDate' responses: '200': description: | JSONL stream. Each line is a `campaign_country_daily` v1.0 row. Lines are sorted by `(report_date asc, country_code)`. headers: Content-Disposition: schema: type: string description: > `attachment; filename="breakdown_{campaignId}_{startDate}_{endDate}.jsonl"` example: >- attachment; filename="breakdown_f1e28d31_2026-04-01_2026-05-01.jsonl" X-Row-Count: schema: type: integer description: Total number of rows in the response. content: application/x-ndjson: schema: $ref: '#/components/schemas/BreakdownRow' example: > {"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.50,"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"} {"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":"DE","impressions":2103,"ad_clicks":48,"link_clicks":31,"streams":87,"listeners":61,"followers":4,"streams_per_listener":1.43,"spend_media":18.20,"spend_total":22.75,"fees":4.55,"currency":"USD","currency_account":"USD","cpl":0.298,"cpf":4.55,"cpc_linkclick":0.587,"ctr_linkclick":0.0148,"ctr_adclick":0.0228,"cost_per_result":4.55,"result_type":"follow"} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - apiKeyAuth: [] - apiKeyBearerAuth: [] components: parameters: campaignId: name: campaignId in: path required: true schema: type: string description: Campaign identifier (UUID) startDate: name: startDate in: query schema: type: string format: date description: Inclusive start date (`YYYY-MM-DD`). Defaults to campaign start date. endDate: name: endDate in: query schema: type: string format: date description: Inclusive end date (`YYYY-MM-DD`). Defaults to today. schemas: BreakdownRow: type: object description: > One row of the `campaign_country_daily` v1.0 schema. Primary key: `(provider, account_id, report_date, campaign_id, country_code)`. Rows are idempotent — re-ingesting on the primary key is safe. Values for a given `report_date` may be revised for up to 7 days after the date closes due to delayed events from Meta and Spotify. required: - provider - account_id - schema_version - report_date - report_date_timezone - exported_at - campaign_id - campaign_name - campaign_target_type - country_code - streams - listeners - followers - streams_per_listener - spend_media - spend_total - fees - currency - currency_account - cpl - cpf - cost_per_result properties: provider: type: string enum: - soundlink description: >- Always `soundlink`. Identifies the data provider for multi-source warehouses. account_id: type: string description: Soundlink organization ID (UUID). schema_version: type: string description: Schema version. Pin your ingest pipeline to this value. example: '1.0' report_date: type: string format: date description: UTC calendar date the metrics belong to (`YYYY-MM-DD`). report_date_timezone: type: string enum: - UTC description: Always `UTC`. exported_at: type: string format: date-time description: >- ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered. campaign_id: type: string description: Soundlink campaign UUID. Stable for the lifetime of the campaign. campaign_name: type: string description: Human-readable campaign name. campaign_target_type: type: string nullable: true enum: - track - playlist description: >- Whether this campaign promotes a track or playlist. `null` if undetermined. campaign_target_isrc: type: string nullable: true description: >- ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`. campaign_target_spotify_track_id: type: string nullable: true description: >- Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`. campaign_target_playlist_id: type: string nullable: true description: >- Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`. country_code: type: string description: >- ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase. impressions: type: integer nullable: true description: Total Meta ad impressions served in this country on this day. ad_clicks: type: integer nullable: true description: >- Total clicks on the Meta ad (all click types). Use `ctr_adclick` for ad-level CTR. link_clicks: type: integer nullable: true description: >- Clicks on "Continue with Spotify" on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR. streams: type: integer description: >- Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates. listeners: type: integer description: >- Unique Spotify listeners attributed to this campaign in this country on this day (7-day click-through window). Summing country rows gives the correct campaign-level total. followers: type: integer description: >- Spotify artist follower gains attributed to this campaign in this country on this day (7-day click-through window). streams_per_listener: type: number description: streams / listeners for this row. Zero if listeners is zero. spend_media: type: number description: >- Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In `currency`. spend_total: type: number description: >- Total billed by Soundlink (spend_media + fees). Computed as `spend_media / (1 - fee_pct)`. fees: type: number description: Soundlink service fee (spend_total - spend_media). currency: type: string description: Currency for spend fields. Currently always `USD`. currency_account: type: string description: >- Account billing currency. Currently always `USD`. Will differ from `currency` once EUR delivery is available. cpl: type: number description: >- Cost per listener (spend_media / listeners). Zero if listeners is zero. cpf: type: number description: >- Cost per follower (spend_media / followers). Zero if followers is zero. cpc_linkclick: type: number nullable: true description: >- Cost per outbound click (spend_media / link_clicks). Null if link_clicks is null or zero. ctr_linkclick: type: number nullable: true description: >- Outbound CTR (link_clicks / impressions). Null if impressions is null or zero. ctr_adclick: type: number nullable: true description: >- Meta ad CTR (ad_clicks / impressions). Null if impressions is null or zero. cost_per_result: type: number description: >- Cost per primary campaign result. Currently equivalent to `cpf` (cost per follower). See `result_type`. result_type: type: string nullable: true enum: - lp_click - stream - follow description: >- The conversion event used for `cost_per_result`. Currently always `follow`. ErrorResponse: type: object required: - error - meta properties: error: $ref: '#/components/schemas/Error' meta: $ref: '#/components/schemas/Meta' Error: type: object required: - code - message properties: code: type: string description: Stable snake_case error code. enum: - invalid_api_key - api_key_revoked - api_key_expired - mixed_credentials - insufficient_scope - not_found - campaign_not_found - invalid_query_parameter - invalid_date_range - page_size_exceeded - invalid_request - invalid_genre - invalid_duration_or_budget - invalid_daily_budget - invalid_duration_days - invalid_spotify_url - invalid_tier_budget_allocation - invalid_tier_status - tier_update_cooldown - wallet_not_enabled - insufficient_credit - idempotency_key_conflict - rate_limit_exceeded - invalid_video_url - video_import_limit_exceeded - video_import_session_not_found - internal_error message: type: string description: Human-readable error description. Do not parse programmatically. details: type: object nullable: true description: | Additive, error-code-specific context (e.g. `available`/`required` on `insufficient_credit`). Absent or `null` for error codes that carry no extra data. additionalProperties: true Meta: type: object required: - requestId properties: requestId: type: string format: uuid description: Server-generated request ID. Include when contacting support. responses: BadRequest: description: Invalid query parameter or date range content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_query_parameter: value: error: code: invalid_query_parameter message: pageSize must be an integer between 1 and 500. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 invalid_date_range: value: error: code: invalid_date_range message: endDate must not be before startDate. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Missing, malformed, revoked, or expired API key headers: Retry-After: schema: type: integer description: Present only on `rate_limit_exceeded` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_api_key: value: error: code: invalid_api_key message: >- Missing or malformed API key. Expected: sk__ (sent via x-api-key or Authorization: Bearer). meta: requestId: 550e8400-e29b-41d4-a716-446655440000 api_key_revoked: value: error: code: api_key_revoked message: >- This API key has been revoked. Create a new key in Settings → Developer → API keys. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Valid key but missing required scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_scope message: This key does not have the metrics:read scope. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: Campaign not found or belongs to another organization content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: campaign_not_found message: Campaign not found. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 RateLimited: description: Per-key rate limit exceeded (60/min, 600/hr) headers: Retry-After: required: true schema: type: integer description: Seconds until the rate limit resets content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: >- Rate limit exceeded. Retry after the number of seconds indicated in the Retry-After header. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 InternalError: description: Unexpected server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: internal_error message: >- An unexpected error occurred. Contact support with the requestId. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: > 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. apiKeyBearerAuth: type: http scheme: bearer description: | Pass your Soundlink `sk_*` API key as a Bearer token: `Authorization: Bearer sk__`. Verified with the exact same key as `apiKeyAuth` — just the recommended header for the same `sk_*` credential. Do not combine with `x-api-key`. ````