> ## 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. # Soundlink engagement export (JSONL) > Streams the full engagement dataset for a soundlink as **newline-delimited JSON (JSONL)**. Every line is a complete, valid JSON object conforming to the `soundlink_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/soundlinks/{soundlinkId}/metrics/engagement/export Accept: application/x-ndjson ``` **Response body (one JSON object per line, no trailing comma):** ``` {"provider":"soundlink","report_date":"2026-08-01","streams":89,...} {"provider":"soundlink","report_date":"2026-08-02","streams":104,...} ``` **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. Re-fetching and re-ingesting on the primary key is safe (idempotent). Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer. ## OpenAPI ````yaml /openapi/soundlink-public-api-v1.yaml get /v1/soundlinks/{soundlinkId}/metrics/engagement/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 `Authorization: Bearer` with one of: 1. **API key (recommended)** — a `sk_*` key from the Soundlink app (Settings → Developer → API keys): ``` Authorization: Bearer sk_abc123_ ``` 2. **OAuth Bearer** — an access token from Sign in with Soundlink (authorization code or client credentials). Token scopes use the same strings as Public API key scopes (for example `campaigns:read`, `metrics:read`): ``` Authorization: Bearer ``` `x-api-key` is no longer accepted and is ignored if sent. Requests without `Authorization: Bearer` return `401 invalid_api_key` (or `401 invalid_token` when a Bearer value is present but neither a recognized `sk_*` key nor a valid OAuth access token). ### Which operations accept OAuth? | Operations | Required scope | Auth | | --- | --- | --- | | `GET /v1/ping` | any granted Public API scope | API key (Bearer) or OAuth Bearer | | Campaign reads (`GET /v1/strategies`, `GET /v1/campaigns`, campaign detail, tiers) | `campaigns:read` | API key (Bearer) or OAuth Bearer | | Metrics reads (overview, breakdown, exports) | `metrics:read` | API key (Bearer) or OAuth Bearer | | Campaign writes (create, stop, budget, tier updates) | `campaigns:write` | API key (Bearer) or OAuth Bearer | | Video import / import status | `videos:write` | API key (Bearer) or OAuth Bearer | | Soundlink reads (list, detail, metrics overview/breakdown/engagement, JSONL exports) | `soundlinks:read` | API key (Bearer) or OAuth Bearer | | Soundlink writes (create, archive) | `soundlinks:write` | API key (Bearer) or OAuth Bearer | Per-operation scope requirements are also marked with `x-required-scope` (except `GET /v1/ping`, which accepts any valid credential with at least one Public API scope granted to the key/token). 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: - apiKeyBearerAuth: [] - oauthBearer: [] 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 - name: Soundlinks description: Soundlink listing, detail, creation, archive, and performance metrics paths: /v1/soundlinks/{soundlinkId}/metrics/engagement/export: get: tags: - Soundlinks summary: Soundlink engagement export (JSONL) description: > Streams the full engagement dataset for a soundlink as **newline-delimited JSON (JSONL)**. Every line is a complete, valid JSON object conforming to the `soundlink_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/soundlinks/{soundlinkId}/metrics/engagement/export Accept: application/x-ndjson ``` **Response body (one JSON object per line, no trailing comma):** ``` {"provider":"soundlink","report_date":"2026-08-01","streams":89,...} {"provider":"soundlink","report_date":"2026-08-02","streams":104,...} ``` **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. Re-fetching and re-ingesting on the primary key is safe (idempotent). Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer. operationId: exportSoundlinkEngagement parameters: - $ref: '#/components/parameters/soundlinkId' - $ref: '#/components/parameters/startDate' - $ref: '#/components/parameters/endDate' - name: engagementContext in: query schema: type: string enum: - catalog - playlist description: Filter to a single engagement context. Omit to return both. responses: '200': description: > JSONL stream. Each line is a `soundlink_engagement_daily` v1.0 row. Lines are sorted by `(report_date asc, engagement_context, country_code, engaged_spotify_track_id)`. headers: Content-Disposition: schema: type: string description: > `attachment; filename="engagement_{soundlinkId}_{startDate}_{endDate}.jsonl"` example: >- attachment; filename="engagement_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl" X-Row-Count: schema: type: integer description: >- Total number of rows in the response. Useful for progress tracking when streaming. content: application/x-ndjson: schema: $ref: '#/components/schemas/SoundlinkEngagementDailyRow' example: > {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"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} {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"playlist","soundlink_target_isrc":null,"soundlink_target_spotify_track_id":null,"soundlink_target_playlist_id":"37i9dQZF1Epwit2GR54N9P","engagement_context":"playlist","country_code":"DE","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":14,"new_listeners":19,"returning_listeners":7,"listeners":26,"new_listener_streams":24,"returning_listener_streams":11,"streams":35,"spl":1.35} '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: - apiKeyBearerAuth: [] - oauthBearer: [] components: parameters: soundlinkId: name: soundlinkId in: path required: true schema: type: string description: >- Soundlink identifier (URL-safe string, same ID used in the public sndl.ink URL) startDate: name: startDate in: query schema: type: string format: date description: | 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: name: endDate in: query schema: type: string format: date description: Inclusive end date (`YYYY-MM-DD`). Defaults to today. schemas: SoundlinkEngagementDailyRow: type: object description: > One row of the `soundlink_engagement_daily` v1.0 schema. Primary key: `(provider, account_id, report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`. 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 Spotify playback events. No `status` field: soundlinks do not store per-day lifecycle history. No financial fields. required: - provider - account_id - schema_version - report_date - report_date_timezone - exported_at - soundlink_id - soundlink_name - soundlink_target_type - engagement_context - country_code - engaged_spotify_track_id - engaged_track_name - new_listeners - returning_listeners - listeners - new_listener_streams - returning_listener_streams - streams - spl 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 string. 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`). Rows can change for up to 7 days after close. 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. soundlink_id: type: string description: Unique ID of this soundlink. example: V1StGXR8_Z5jdHi6B-myT soundlink_name: type: string description: Human-readable soundlink name. soundlink_target_type: type: string nullable: true enum: - track - playlist description: >- Whether this soundlink promotes a track or playlist. `null` if undetermined. soundlink_target_isrc: type: string nullable: true description: >- ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`. soundlink_target_spotify_track_id: type: string nullable: true description: >- Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`. soundlink_target_playlist_id: type: string nullable: true description: >- Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`. engagement_context: type: string enum: - catalog - playlist description: > Which section this row belongs to. `catalog`: plays of the promoted track and same-artist catalog tracks (track soundlinks). `playlist`: per-track performance inside the promoted playlist (playlist soundlinks). country_code: type: string description: >- ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase. example: US engaged_track_isrc: type: string nullable: true description: > ISRC of the track that received listens. May differ from `soundlink_target_isrc` for catalog spillover rows. `null` if ISRC could not be resolved. engaged_spotify_track_id: type: string description: Spotify track ID of the engaged track. Part of the primary key. example: 4cOdK2wGLETKBW3PvgPWqT engaged_track_name: type: string description: Display name of the engaged track. playlist_position: type: integer nullable: true minimum: 1 description: > 1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top). Populated only when `engagement_context = playlist`. Treat `null` as unavailable, not an error. new_listeners: type: integer minimum: 0 description: >- Unique listeners whose first play of this track via this soundlink occurred on `report_date`. returning_listeners: type: integer minimum: 0 description: >- Unique listeners who played this track on `report_date` but whose first play was on an earlier date. listeners: type: integer minimum: 0 description: > Total unique listeners on `report_date`: `new_listeners + returning_listeners`. **Do not sum across days** — the same listener can appear on multiple `report_date` rows. new_listener_streams: type: integer minimum: 0 description: Stream count from new listeners on `report_date`. returning_listener_streams: type: integer minimum: 0 description: Stream count from returning listeners on `report_date`. streams: type: integer minimum: 0 description: > Total streams on `report_date`: `new_listener_streams + returning_listener_streams`. Safe to sum within a day; summing across days counts repeat listens. spl: type: number description: >- Streams per listener (`streams / listeners`). Zero if `listeners` is zero. 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 - 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 or invalid credentials. Covers missing/malformed API keys, invalid or expired OAuth access tokens, and revoked API keys. `x-api-key` is not accepted and is ignored if sent. 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 credentials. Send Authorization: Bearer.' meta: requestId: 550e8400-e29b-41d4-a716-446655440000 invalid_token: value: error: code: invalid_token message: OAuth access token is invalid or expired. 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: | Authenticated but not allowed: missing required scope, or OAuth access disabled for the organization (`access_denied`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficient_scope: value: error: code: insufficient_scope message: This token does not have the metrics:read scope. meta: requestId: 550e8400-e29b-41d4-a716-446655440000 access_denied: value: error: code: access_denied message: OAuth access is not enabled for this organization. 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: apiKeyBearerAuth: type: http scheme: bearer description: | Pass your Soundlink `sk_*` API key as a Bearer token: `Authorization: Bearer sk__` (not an OAuth token; see `oauthBearer` for that). Accepted on all Public API operations. Send only one `Authorization` header per request. oauthBearer: type: http scheme: bearer bearerFormat: JWT description: | OAuth 2.0 access token from Sign in with Soundlink (`Authorization: Bearer `). Token scopes must include the operation's required scope (see `x-required-scope` and the Authentication section). Accepted on all Public API operations (reads and writes). ````