soundlink 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -39,7 +39,7 @@ info:
39
39
  | Metrics reads (overview, breakdown, exports) | `metrics:read` | API key (Bearer) or OAuth Bearer |
40
40
  | Campaign writes (create, stop, budget, tier updates) | `campaigns:write` | API key (Bearer) or OAuth Bearer |
41
41
  | Video import / import status | `videos:write` | API key (Bearer) or OAuth Bearer |
42
- | Soundlink reads (list, detail, metrics overview/timeseries/engagement) | `soundlinks:read` | API key (Bearer) or OAuth Bearer |
42
+ | Soundlink reads (list, detail, metrics overview/timeseries/breakdown/engagement, JSONL exports) | `soundlinks:read` | API key (Bearer) or OAuth Bearer |
43
43
 
44
44
  Per-operation scope requirements are also marked with `x-required-scope`
45
45
  (except `GET /v1/ping`, which accepts any valid credential with at least
@@ -873,6 +873,116 @@ paths:
873
873
  '429': { $ref: '#/components/responses/RateLimited' }
874
874
  '500': { $ref: '#/components/responses/InternalError' }
875
875
 
876
+ /v1/campaigns/{campaignId}/metrics/engagement:
877
+ get:
878
+ operationId: getCampaignEngagement
879
+ summary: Campaign engagement breakdown
880
+ description: |
881
+ Per-day, per-track engagement metrics for a campaign. One row per
882
+ `(report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)`.
883
+ Results are paginated.
884
+
885
+ **Row schema:** `campaign_engagement_daily` v1.0 — the same schema used
886
+ in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting
887
+ is safe.
888
+
889
+ **Key difference from `/metrics/breakdown`:** this endpoint covers the
890
+ full engagement window — including post-campaign streaming activity —
891
+ not just dates when the campaign was actively running.
892
+
893
+ **`engagement_context` values:**
894
+ - `catalog` — same-artist spillover (and direct promoted-track plays)
895
+ on track campaigns.
896
+ - `playlist` — per-track performance inside the promoted playlist on
897
+ playlist campaigns.
898
+
899
+ **`listeners` is deduplicated within each row only.** Do not sum
900
+ `listeners` across days to get a campaign total.
901
+
902
+ **Date range:** if you omit both dates, defaults to the last **90 days**
903
+ ending today. Override with `startDate` / `endDate`. **Responses are
904
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
905
+
906
+ **Mutability window:** rows for a given `report_date` can be revised
907
+ for up to 7 days after the date closes due to delayed Spotify
908
+ playback events.
909
+
910
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
911
+ tags: [Metrics]
912
+ security:
913
+ - apiKeyBearerAuth: []
914
+ - oauthBearer: []
915
+ x-required-scope: metrics:read
916
+ parameters:
917
+ - $ref: '#/components/parameters/campaignId'
918
+ - $ref: '#/components/parameters/startDate'
919
+ - $ref: '#/components/parameters/endDate'
920
+ - name: engagementContext
921
+ in: query
922
+ schema:
923
+ type: string
924
+ enum: [catalog, playlist]
925
+ description: Filter to a single engagement context. Omit to return both.
926
+ - $ref: '#/components/parameters/page'
927
+ - $ref: '#/components/parameters/pageSize500'
928
+ - name: sortBy
929
+ in: query
930
+ schema:
931
+ type: string
932
+ enum: [report_date]
933
+ default: report_date
934
+ - $ref: '#/components/parameters/sortOrder'
935
+ responses:
936
+ '200':
937
+ description: Paginated engagement rows (`campaign_engagement_daily` schema)
938
+ content:
939
+ application/json:
940
+ schema:
941
+ $ref: '#/components/schemas/MetricsEngagementResponse'
942
+ example:
943
+ data:
944
+ schemaVersion: '1.0'
945
+ items:
946
+ - provider: soundlink
947
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112cc9a
948
+ schema_version: '1.0'
949
+ report_date: '2026-04-08'
950
+ report_date_timezone: UTC
951
+ exported_at: '2026-05-22T10:12:11Z'
952
+ campaign_id: 8ccd7b88-2591-4b94-848f-f142f5c6bba1
953
+ campaign_name: 9 To 5
954
+ campaign_target_type: track
955
+ campaign_target_isrc: DEXW62500272
956
+ campaign_target_spotify_track_id: 2RkZ5WPkKyBf0u8vN3dNgb
957
+ campaign_target_playlist_id: null
958
+ status: ended
959
+ engagement_context: catalog
960
+ country_code: US
961
+ engaged_track_isrc: DEXW62500001
962
+ engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
963
+ engaged_track_name: Till The Sunrise
964
+ playlist_position: null
965
+ new_listeners: 42
966
+ returning_listeners: 18
967
+ listeners: 60
968
+ new_listener_streams: 58
969
+ returning_listener_streams: 31
970
+ streams: 89
971
+ spl: 1.48
972
+ pagination:
973
+ page: 1
974
+ pageSize: 50
975
+ totalCount: 120
976
+ totalPages: 3
977
+ meta:
978
+ requestId: 550e8400-e29b-41d4-a716-446655440000
979
+ '400': { $ref: '#/components/responses/BadRequest' }
980
+ '401': { $ref: '#/components/responses/Unauthorized' }
981
+ '403': { $ref: '#/components/responses/Forbidden' }
982
+ '404': { $ref: '#/components/responses/NotFound' }
983
+ '429': { $ref: '#/components/responses/RateLimited' }
984
+ '500': { $ref: '#/components/responses/InternalError' }
985
+
876
986
  /v1/campaigns/{campaignId}/metrics/engagement/export:
877
987
  get:
878
988
  operationId: exportCampaignEngagement
@@ -880,7 +990,9 @@ paths:
880
990
  description: |
881
991
  Streams the full engagement dataset for a campaign as
882
992
  **newline-delimited JSON (JSONL)**. Every line is a complete, valid
883
- JSON object conforming to the `campaign_engagement_daily` v1.0 schema.
993
+ JSON object conforming to the `campaign_engagement_daily` v1.0 schema
994
+ — identical to the rows returned by `GET /metrics/engagement` but
995
+ without pagination or an envelope wrapper.
884
996
 
885
997
  Designed for data pipeline consumers: load directly into BigQuery,
886
998
  Snowflake, or any JSONL-aware ingest tool without cursor logic.
@@ -1061,10 +1173,12 @@ paths:
1061
1173
  summary: Soundlink metrics overview
1062
1174
  description: |
1063
1175
  Soundlink-level totals for a date range: landing page views, outbound
1064
- clicks, listeners (with new/returning splits), streams, followers, and
1065
- derived ratios. No per-day rows — use `/metrics/timeseries` for those.
1066
-
1067
- Maps to the **Overview** tab in the Soundlink Insights UI.
1176
+ clicks, listeners, streams, followers, and derived ratios. Totals are
1177
+ sums of country-day mart rows (`api_smart_link_country_daily`);
1178
+ `listeners` is the sum of daily country `new_listeners` (not
1179
+ period-unique). No per-day rows — use `/metrics/timeseries` for those,
1180
+ or `/metrics/breakdown` for country-day rows (including new/returning
1181
+ splits).
1068
1182
 
1069
1183
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1070
1184
  tags: [Soundlinks]
@@ -1088,13 +1202,9 @@ paths:
1088
1202
  views: 4821
1089
1203
  link_clicks: 890
1090
1204
  streams: 9340
1091
- listeners: 4821
1092
- new_listeners: 3980
1093
- returning_listeners: 841
1094
- new_listener_streams: 7104
1095
- returning_listener_streams: 2236
1205
+ listeners: 3980
1096
1206
  followers: 312
1097
- streams_per_listener: 1.94
1207
+ streams_per_listener: 2.35
1098
1208
  ctr_lp: 0.185
1099
1209
  meta:
1100
1210
  requestId: 550e8400-e29b-41d4-a716-446655440000
@@ -1121,11 +1231,11 @@ paths:
1121
1231
  for up to 7 days after the date closes due to delayed Spotify playback
1122
1232
  events. Re-fetch or re-ingest accordingly.
1123
1233
 
1124
- Rows are aggregated across countries (no `country_code` in v1.0) and
1125
- contain no financial fields.
1234
+ Rows are aggregated across countries (no `country_code`) and
1235
+ contain no financial fields. For country-day rows use
1236
+ `/metrics/breakdown` (and `/metrics/breakdown/export`).
1126
1237
 
1127
1238
  Maps to the **Trends** tab in the Soundlink Insights UI.
1128
- Use for daily warehouse loads.
1129
1239
 
1130
1240
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1131
1241
  tags: [Soundlinks]
@@ -1194,20 +1304,29 @@ paths:
1194
1304
  '429': { $ref: '#/components/responses/RateLimited' }
1195
1305
  '500': { $ref: '#/components/responses/InternalError' }
1196
1306
 
1197
- /v1/soundlinks/{soundlinkId}/metrics/engagement:
1307
+ /v1/soundlinks/{soundlinkId}/metrics/breakdown:
1198
1308
  get:
1199
- operationId: getSoundlinkEngagement
1200
- summary: Soundlink engagement (top tracks)
1309
+ operationId: getSoundlinkMetricsBreakdown
1310
+ summary: Soundlink metrics breakdown
1201
1311
  description: |
1202
- Top tracks for a soundlink, aggregated over the requested date range.
1203
- One item per track, sorted by streams by default. Results are
1204
- paginated.
1312
+ Per-day metrics broken down by country. One row per
1313
+ `(report_date, soundlink_id, country_code)`. Can be large, so results
1314
+ are paginated.
1315
+
1316
+ **Row schema:** `soundlink_country_daily` v1.0 — the same schema used
1317
+ in JSONL bulk exports. Rows are idempotent on the primary key
1318
+ `(provider, account_id, report_date, soundlink_id, country_code)`;
1319
+ re-ingesting is safe.
1205
1320
 
1206
- Returns period totals per track (not daily rows). Maps to the top
1207
- tracks section of the **Overview** tab in the Soundlink Insights UI.
1208
- `startDate`/`endDate` snap to the same Insights windows: yesterday,
1209
- last 7 days (inclusive span ending today), or all-time. Omitting
1210
- `startDate` always uses all-time (it is not inferred from createdAt).
1321
+ **Mutability window:** rows for a given `report_date` can be revised
1322
+ for up to 7 days after the date closes due to delayed Spotify playback
1323
+ events. Re-fetch or re-ingest accordingly.
1324
+
1325
+ Rows contain no financial fields: ads for self-serve soundlinks run
1326
+ in your own Meta account, so spend is not visible to Soundlink.
1327
+
1328
+ Maps to the **Countries** tab in the Soundlink Insights UI.
1329
+ Use `/metrics/timeseries` for country-aggregated daily Trends rows.
1211
1330
 
1212
1331
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1213
1332
  tags: [Soundlinks]
@@ -1217,42 +1336,57 @@ paths:
1217
1336
  x-required-scope: soundlinks:read
1218
1337
  parameters:
1219
1338
  - $ref: '#/components/parameters/soundlinkId'
1220
- - $ref: '#/components/parameters/soundlinkEngagementStartDate'
1339
+ - $ref: '#/components/parameters/soundlinkStartDate'
1221
1340
  - $ref: '#/components/parameters/soundlinkEndDate'
1222
1341
  - $ref: '#/components/parameters/page'
1223
- - $ref: '#/components/parameters/pageSize100'
1342
+ - $ref: '#/components/parameters/pageSize500'
1224
1343
  - name: sortBy
1225
1344
  in: query
1226
1345
  schema:
1227
1346
  type: string
1228
- enum: [totalStreams, totalListeners]
1229
- default: totalStreams
1347
+ enum: [report_date, country_code]
1348
+ default: report_date
1230
1349
  - $ref: '#/components/parameters/sortOrder'
1231
1350
  responses:
1232
1351
  '200':
1233
- description: Paginated aggregated top tracks
1352
+ description: Paginated per-day country rows (`soundlink_country_daily` schema)
1234
1353
  content:
1235
1354
  application/json:
1236
1355
  schema:
1237
- $ref: '#/components/schemas/SoundlinkEngagementResponse'
1356
+ $ref: '#/components/schemas/SoundlinkBreakdownResponse'
1238
1357
  example:
1239
1358
  data:
1359
+ schemaVersion: '1.0'
1240
1360
  items:
1241
- - trackId: 11dFghVXANMlKmJXsNCbNl
1242
- trackName: Midnight Drive
1243
- totalStreams: 892
1244
- totalListeners: 603
1245
- streamsPerListener: 1.48
1246
- - trackId: 4cOdK2wGLETKBW3PvgPWqT
1247
- trackName: Till The Sunrise
1248
- totalStreams: 411
1249
- totalListeners: 322
1250
- streamsPerListener: 1.28
1361
+ - provider: soundlink
1362
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
1363
+ schema_version: '1.0'
1364
+ report_date: '2026-08-01'
1365
+ report_date_timezone: UTC
1366
+ exported_at: '2026-08-28T03:00:00Z'
1367
+ soundlink_id: V1StGXR8_Z5jdHi6B-myT
1368
+ soundlink_name: Midnight Drive
1369
+ soundlink_target_type: track
1370
+ soundlink_target_isrc: DEXW62500259
1371
+ soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1372
+ soundlink_target_playlist_id: null
1373
+ country_code: US
1374
+ views: 4821
1375
+ link_clicks: 890
1376
+ streams: 203
1377
+ listeners: 145
1378
+ new_listeners: 120
1379
+ returning_listeners: 25
1380
+ new_listener_streams: 160
1381
+ returning_listener_streams: 43
1382
+ followers: 12
1383
+ streams_per_listener: 1.4
1384
+ ctr_lp: 0.185
1251
1385
  pagination:
1252
1386
  page: 1
1253
- pageSize: 10
1254
- totalCount: 24
1255
- totalPages: 3
1387
+ pageSize: 50
1388
+ totalCount: 340
1389
+ totalPages: 7
1256
1390
  meta:
1257
1391
  requestId: 550e8400-e29b-41d4-a716-446655440000
1258
1392
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -1262,100 +1396,362 @@ paths:
1262
1396
  '429': { $ref: '#/components/responses/RateLimited' }
1263
1397
  '500': { $ref: '#/components/responses/InternalError' }
1264
1398
 
1265
- /v1/videos/import:
1266
- post:
1267
- operationId: importVideo
1268
- summary: Import video(s) from public HTTPS MP4 URL(s)
1399
+ /v1/soundlinks/{soundlinkId}/metrics/breakdown/export:
1400
+ get:
1401
+ operationId: exportSoundlinkMetricsBreakdown
1402
+ summary: Soundlink metrics breakdown export (JSONL)
1269
1403
  description: |
1270
- Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
1271
- session, enqueues async download/staging, and returns `202` with `sessionId`.
1404
+ Streams the full country-level metrics dataset for a soundlink as
1405
+ **newline-delimited JSON (JSONL)**. Every line is a complete, valid
1406
+ JSON object conforming to the `soundlink_country_daily` v1.0 schema
1407
+ — identical to the rows returned by `GET /metrics/breakdown` but
1408
+ without pagination or an envelope wrapper.
1272
1409
 
1273
- Requires the `videos:write` scope. Subject to a stricter per-credential rate
1274
- limit than generic public API routes (default 20 imports per hour per API key
1275
- or OAuth grant). This caps how many import requests are accepted per hour,
1276
- not how long ingestion takes.
1410
+ Designed for data pipeline consumers: load directly into BigQuery,
1411
+ Snowflake, or any JSONL-aware ingest tool without cursor logic.
1277
1412
 
1278
- Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready`, `partial`,
1279
- or `failed`. For single-URL imports, use `videoId` when ready. For batches
1280
- (`count > 1`), use `videoIds`.
1281
- tags: [Videos]
1413
+ **Usage:**
1414
+ ```
1415
+ GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export
1416
+ Accept: application/x-ndjson
1417
+ ```
1418
+
1419
+ **Date range:** if you omit both dates, defaults to the last **90 days**
1420
+ ending today. Override with `startDate` / `endDate`. **Responses are
1421
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
1422
+ Page longer histories in 90-day slices.
1423
+
1424
+ **Mutability:** rows for a given `report_date` can be revised for up
1425
+ to 7 days after the date closes due to delayed Spotify playback
1426
+ events. Re-fetching and re-ingesting on the primary key is safe
1427
+ (idempotent).
1428
+
1429
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1430
+ tags: [Soundlinks]
1282
1431
  security:
1283
1432
  - apiKeyBearerAuth: []
1284
1433
  - oauthBearer: []
1285
- x-required-scope: videos:write
1286
- requestBody:
1287
- required: true
1288
- content:
1289
- application/json:
1290
- schema:
1291
- $ref: '#/components/schemas/VideoImportRequest'
1292
- examples:
1293
- single:
1294
- summary: Single URL (legacy)
1295
- value:
1296
- url: 'https://cdn.example.com/promo.mp4'
1297
- batch:
1298
- summary: Batch of URLs
1299
- value:
1300
- videos:
1301
- - url: 'https://cdn.example.com/a.mp4'
1302
- - url: 'https://cdn.example.com/b.mp4'
1434
+ x-required-scope: soundlinks:read
1435
+ parameters:
1436
+ - $ref: '#/components/parameters/soundlinkId'
1437
+ - $ref: '#/components/parameters/startDate'
1438
+ - $ref: '#/components/parameters/endDate'
1303
1439
  responses:
1304
1440
  '200':
1305
- description: Duplicate video already in the organization's library (sync legacy path only)
1306
- content:
1307
- application/json:
1441
+ description: |
1442
+ JSONL stream. Each line is a `soundlink_country_daily` v1.0 row.
1443
+ Lines are sorted by `(report_date asc, country_code)`.
1444
+ headers:
1445
+ Content-Disposition:
1308
1446
  schema:
1309
- $ref: '#/components/schemas/VideoImportStartResponse'
1310
- '202':
1311
- description: Import accepted; ingestion in progress
1447
+ type: string
1448
+ description: |
1449
+ `attachment; filename="breakdown_{soundlinkId}_{startDate}_{endDate}.jsonl"`
1450
+ example: 'attachment; filename="breakdown_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
1451
+ X-Row-Count:
1452
+ schema:
1453
+ type: integer
1454
+ description: Total number of rows in the response.
1312
1455
  content:
1313
- application/json:
1456
+ application/x-ndjson:
1314
1457
  schema:
1315
- $ref: '#/components/schemas/VideoImportStartResponse'
1458
+ $ref: '#/components/schemas/SoundlinkCountryDailyRow'
1459
+ example: |
1460
+ {"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,"country_code":"US","views":4821,"link_clicks":890,"streams":203,"listeners":145,"new_listeners":120,"returning_listeners":25,"new_listener_streams":160,"returning_listener_streams":43,"followers":12,"streams_per_listener":1.4,"ctr_lp":0.185}
1461
+ {"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,"country_code":"DE","views":2103,"link_clicks":31,"streams":87,"listeners":61,"new_listeners":48,"returning_listeners":13,"new_listener_streams":64,"returning_listener_streams":23,"followers":4,"streams_per_listener":1.43,"ctr_lp":0.0147}
1316
1462
  '400': { $ref: '#/components/responses/BadRequest' }
1317
1463
  '401': { $ref: '#/components/responses/Unauthorized' }
1318
1464
  '403': { $ref: '#/components/responses/Forbidden' }
1465
+ '404': { $ref: '#/components/responses/NotFound' }
1319
1466
  '429': { $ref: '#/components/responses/RateLimited' }
1320
1467
  '500': { $ref: '#/components/responses/InternalError' }
1321
1468
 
1322
- /v1/videos/import/{sessionId}:
1469
+ /v1/soundlinks/{soundlinkId}/metrics/engagement:
1323
1470
  get:
1324
- operationId: getVideoImportStatus
1325
- summary: Get video import session status
1471
+ operationId: getSoundlinkEngagement
1472
+ summary: Soundlink engagement breakdown
1326
1473
  description: |
1327
- Returns processing status. For single-URL sessions, includes `videoId` when ready.
1328
- For batch sessions (`count > 1`), includes `videoIds` and `counts`.
1329
- Requires the `videos:write` scope.
1330
- tags: [Videos]
1474
+ Per-day, per-track engagement metrics for a soundlink. One row per
1475
+ `(report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
1476
+ Results are paginated.
1477
+
1478
+ **Row schema:** `soundlink_engagement_daily` v1.0 — the same schema used
1479
+ in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting
1480
+ is safe.
1481
+
1482
+ **Key difference from `/metrics/breakdown`:** breakdown aggregates
1483
+ views, streams, and listeners by **country** (`soundlink_country_daily`);
1484
+ engagement breaks down **which tracks** listeners played, including
1485
+ catalog spillover and playlist slot performance (`engagement_context`,
1486
+ `engaged_spotify_track_id`).
1487
+
1488
+ **`engagement_context` values:**
1489
+ - `catalog` — same-artist spillover (and direct promoted-track plays)
1490
+ on track soundlinks.
1491
+ - `playlist` — per-track performance inside the promoted playlist on
1492
+ playlist soundlinks.
1493
+
1494
+ **`listeners` is deduplicated within each row only.** Do not sum
1495
+ `listeners` across days to get a soundlink total.
1496
+
1497
+ **Date range:** if you omit both dates, defaults to the last **90 days**
1498
+ ending today. Override with `startDate` / `endDate`. **Responses are
1499
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
1500
+
1501
+ **Mutability window:** rows for a given `report_date` can be revised
1502
+ for up to 7 days after the date closes due to delayed Spotify
1503
+ playback events.
1504
+
1505
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1506
+ tags: [Soundlinks]
1331
1507
  security:
1332
1508
  - apiKeyBearerAuth: []
1333
1509
  - oauthBearer: []
1334
- x-required-scope: videos:write
1510
+ x-required-scope: soundlinks:read
1335
1511
  parameters:
1336
- - name: sessionId
1337
- in: path
1338
- required: true
1512
+ - $ref: '#/components/parameters/soundlinkId'
1513
+ - $ref: '#/components/parameters/startDate'
1514
+ - $ref: '#/components/parameters/endDate'
1515
+ - name: engagementContext
1516
+ in: query
1339
1517
  schema:
1340
1518
  type: string
1341
- format: uuid
1342
- description: Upload session ID returned by `POST /v1/videos/import`
1519
+ enum: [catalog, playlist]
1520
+ description: Filter to a single engagement context. Omit to return both.
1521
+ - $ref: '#/components/parameters/page'
1522
+ - $ref: '#/components/parameters/pageSize500'
1523
+ - name: sortBy
1524
+ in: query
1525
+ schema:
1526
+ type: string
1527
+ enum: [report_date]
1528
+ default: report_date
1529
+ - $ref: '#/components/parameters/sortOrder'
1343
1530
  responses:
1344
1531
  '200':
1345
- description: Import session status
1532
+ description: Paginated engagement rows (`soundlink_engagement_daily` schema)
1346
1533
  content:
1347
1534
  application/json:
1348
1535
  schema:
1349
- $ref: '#/components/schemas/VideoImportStatusResponse'
1350
- '401': { $ref: '#/components/responses/Unauthorized' }
1351
- '403': { $ref: '#/components/responses/Forbidden' }
1352
- '404': { $ref: '#/components/responses/NotFound' }
1353
- '429': { $ref: '#/components/responses/RateLimited' }
1354
- '500': { $ref: '#/components/responses/InternalError' }
1355
-
1356
- components:
1357
- securitySchemes:
1358
- apiKeyBearerAuth:
1536
+ $ref: '#/components/schemas/SoundlinkEngagementResponse'
1537
+ example:
1538
+ data:
1539
+ schemaVersion: '1.0'
1540
+ items:
1541
+ - provider: soundlink
1542
+ account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
1543
+ schema_version: '1.0'
1544
+ report_date: '2026-08-01'
1545
+ report_date_timezone: UTC
1546
+ exported_at: '2026-08-28T03:00:00Z'
1547
+ soundlink_id: V1StGXR8_Z5jdHi6B-myT
1548
+ soundlink_name: Midnight Drive
1549
+ soundlink_target_type: track
1550
+ soundlink_target_isrc: DEXW62500259
1551
+ soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1552
+ soundlink_target_playlist_id: null
1553
+ engagement_context: catalog
1554
+ country_code: US
1555
+ engaged_track_isrc: DEXW62500001
1556
+ engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
1557
+ engaged_track_name: Till The Sunrise
1558
+ playlist_position: null
1559
+ new_listeners: 42
1560
+ returning_listeners: 18
1561
+ listeners: 60
1562
+ new_listener_streams: 58
1563
+ returning_listener_streams: 31
1564
+ streams: 89
1565
+ spl: 1.48
1566
+ pagination:
1567
+ page: 1
1568
+ pageSize: 50
1569
+ totalCount: 120
1570
+ totalPages: 3
1571
+ meta:
1572
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1573
+ '400': { $ref: '#/components/responses/BadRequest' }
1574
+ '401': { $ref: '#/components/responses/Unauthorized' }
1575
+ '403': { $ref: '#/components/responses/Forbidden' }
1576
+ '404': { $ref: '#/components/responses/NotFound' }
1577
+ '429': { $ref: '#/components/responses/RateLimited' }
1578
+ '500': { $ref: '#/components/responses/InternalError' }
1579
+
1580
+ /v1/soundlinks/{soundlinkId}/metrics/engagement/export:
1581
+ get:
1582
+ operationId: exportSoundlinkEngagement
1583
+ summary: Soundlink engagement export (JSONL)
1584
+ description: |
1585
+ Streams the full engagement dataset for a soundlink as
1586
+ **newline-delimited JSON (JSONL)**. Every line is a complete, valid
1587
+ JSON object conforming to the `soundlink_engagement_daily` v1.0 schema
1588
+ — identical to the rows returned by `GET /metrics/engagement` but
1589
+ without pagination or an envelope wrapper.
1590
+
1591
+ Designed for data pipeline consumers: load directly into BigQuery,
1592
+ Snowflake, or any JSONL-aware ingest tool without cursor logic.
1593
+
1594
+ **Usage:**
1595
+ ```
1596
+ GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export
1597
+ Accept: application/x-ndjson
1598
+ ```
1599
+
1600
+ **Response body (one JSON object per line, no trailing comma):**
1601
+ ```
1602
+ {"provider":"soundlink","report_date":"2026-08-01","streams":89,...}
1603
+ {"provider":"soundlink","report_date":"2026-08-02","streams":104,...}
1604
+ ```
1605
+
1606
+ **Date range:** if you omit both dates, defaults to the last **90 days**
1607
+ ending today. Override with `startDate` / `endDate`. **Responses are
1608
+ capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
1609
+ Page longer histories in 90-day slices.
1610
+
1611
+ **Mutability:** rows for a given `report_date` can be revised for up to
1612
+ 7 days after the date closes. Re-fetching and re-ingesting on the
1613
+ primary key is safe (idempotent).
1614
+
1615
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1616
+ tags: [Soundlinks]
1617
+ security:
1618
+ - apiKeyBearerAuth: []
1619
+ - oauthBearer: []
1620
+ x-required-scope: soundlinks:read
1621
+ parameters:
1622
+ - $ref: '#/components/parameters/soundlinkId'
1623
+ - $ref: '#/components/parameters/startDate'
1624
+ - $ref: '#/components/parameters/endDate'
1625
+ - name: engagementContext
1626
+ in: query
1627
+ schema:
1628
+ type: string
1629
+ enum: [catalog, playlist]
1630
+ description: Filter to a single engagement context. Omit to return both.
1631
+ responses:
1632
+ '200':
1633
+ description: |
1634
+ JSONL stream. Each line is a `soundlink_engagement_daily` v1.0 row.
1635
+ Lines are sorted by `(report_date asc, engagement_context, country_code, engaged_spotify_track_id)`.
1636
+ headers:
1637
+ Content-Disposition:
1638
+ schema:
1639
+ type: string
1640
+ description: |
1641
+ `attachment; filename="engagement_{soundlinkId}_{startDate}_{endDate}.jsonl"`
1642
+ example: 'attachment; filename="engagement_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
1643
+ X-Row-Count:
1644
+ schema:
1645
+ type: integer
1646
+ description: Total number of rows in the response. Useful for progress tracking when streaming.
1647
+ content:
1648
+ application/x-ndjson:
1649
+ schema:
1650
+ $ref: '#/components/schemas/SoundlinkEngagementDailyRow'
1651
+ example: |
1652
+ {"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}
1653
+ {"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}
1654
+ '400': { $ref: '#/components/responses/BadRequest' }
1655
+ '401': { $ref: '#/components/responses/Unauthorized' }
1656
+ '403': { $ref: '#/components/responses/Forbidden' }
1657
+ '404': { $ref: '#/components/responses/NotFound' }
1658
+ '429': { $ref: '#/components/responses/RateLimited' }
1659
+ '500': { $ref: '#/components/responses/InternalError' }
1660
+
1661
+ /v1/videos/import:
1662
+ post:
1663
+ operationId: importVideo
1664
+ summary: Import video(s) from public HTTPS MP4 URL(s)
1665
+ description: |
1666
+ Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
1667
+ session, enqueues async download/staging, and returns `202` with `sessionId`.
1668
+
1669
+ Requires the `videos:write` scope. Subject to a stricter per-credential rate
1670
+ limit than generic public API routes (default 20 imports per hour per API key
1671
+ or OAuth grant). This caps how many import requests are accepted per hour,
1672
+ not how long ingestion takes.
1673
+
1674
+ Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready`, `partial`,
1675
+ or `failed`. For single-URL imports, use `videoId` when ready. For batches
1676
+ (`count > 1`), use `videoIds`.
1677
+ tags: [Videos]
1678
+ security:
1679
+ - apiKeyBearerAuth: []
1680
+ - oauthBearer: []
1681
+ x-required-scope: videos:write
1682
+ requestBody:
1683
+ required: true
1684
+ content:
1685
+ application/json:
1686
+ schema:
1687
+ $ref: '#/components/schemas/VideoImportRequest'
1688
+ examples:
1689
+ single:
1690
+ summary: Single URL (legacy)
1691
+ value:
1692
+ url: 'https://cdn.example.com/promo.mp4'
1693
+ batch:
1694
+ summary: Batch of URLs
1695
+ value:
1696
+ videos:
1697
+ - url: 'https://cdn.example.com/a.mp4'
1698
+ - url: 'https://cdn.example.com/b.mp4'
1699
+ responses:
1700
+ '200':
1701
+ description: Duplicate video already in the organization's library (sync legacy path only)
1702
+ content:
1703
+ application/json:
1704
+ schema:
1705
+ $ref: '#/components/schemas/VideoImportStartResponse'
1706
+ '202':
1707
+ description: Import accepted; ingestion in progress
1708
+ content:
1709
+ application/json:
1710
+ schema:
1711
+ $ref: '#/components/schemas/VideoImportStartResponse'
1712
+ '400': { $ref: '#/components/responses/BadRequest' }
1713
+ '401': { $ref: '#/components/responses/Unauthorized' }
1714
+ '403': { $ref: '#/components/responses/Forbidden' }
1715
+ '429': { $ref: '#/components/responses/RateLimited' }
1716
+ '500': { $ref: '#/components/responses/InternalError' }
1717
+
1718
+ /v1/videos/import/{sessionId}:
1719
+ get:
1720
+ operationId: getVideoImportStatus
1721
+ summary: Get video import session status
1722
+ description: |
1723
+ Returns processing status. For single-URL sessions, includes `videoId` when ready.
1724
+ For batch sessions (`count > 1`), includes `videoIds` and `counts`.
1725
+ Requires the `videos:write` scope.
1726
+ tags: [Videos]
1727
+ security:
1728
+ - apiKeyBearerAuth: []
1729
+ - oauthBearer: []
1730
+ x-required-scope: videos:write
1731
+ parameters:
1732
+ - name: sessionId
1733
+ in: path
1734
+ required: true
1735
+ schema:
1736
+ type: string
1737
+ format: uuid
1738
+ description: Upload session ID returned by `POST /v1/videos/import`
1739
+ responses:
1740
+ '200':
1741
+ description: Import session status
1742
+ content:
1743
+ application/json:
1744
+ schema:
1745
+ $ref: '#/components/schemas/VideoImportStatusResponse'
1746
+ '401': { $ref: '#/components/responses/Unauthorized' }
1747
+ '403': { $ref: '#/components/responses/Forbidden' }
1748
+ '404': { $ref: '#/components/responses/NotFound' }
1749
+ '429': { $ref: '#/components/responses/RateLimited' }
1750
+ '500': { $ref: '#/components/responses/InternalError' }
1751
+
1752
+ components:
1753
+ securitySchemes:
1754
+ apiKeyBearerAuth:
1359
1755
  type: http
1360
1756
  scheme: bearer
1361
1757
  description: |
@@ -1472,18 +1868,6 @@ components:
1472
1868
  Inclusive start date (`YYYY-MM-DD`) for soundlink overview and
1473
1869
  timeseries. Defaults to the soundlink creation date when omitted.
1474
1870
 
1475
- soundlinkEngagementStartDate:
1476
- name: startDate
1477
- in: query
1478
- schema:
1479
- type: string
1480
- format: date
1481
- description: |
1482
- Inclusive start date (`YYYY-MM-DD`) for soundlink engagement
1483
- (top tracks). Omit for all-time (not createdAt). When set, snaps
1484
- to Insights windows (yesterday / last 7 days ending today /
1485
- all-time); other ranges resolve to all-time.
1486
-
1487
1871
  soundlinkEndDate:
1488
1872
  name: endDate
1489
1873
  in: query
@@ -1528,9 +1912,7 @@ components:
1528
1912
  - invalid_api_key
1529
1913
  - api_key_revoked
1530
1914
  - api_key_expired
1531
- - invalid_token
1532
1915
  - insufficient_scope
1533
- - access_denied
1534
1916
  - not_found
1535
1917
  - campaign_not_found
1536
1918
  - invalid_query_parameter
@@ -2352,6 +2734,27 @@ components:
2352
2734
  meta:
2353
2735
  $ref: '#/components/schemas/Meta'
2354
2736
 
2737
+ MetricsEngagementResponse:
2738
+ type: object
2739
+ required: [data, meta]
2740
+ properties:
2741
+ data:
2742
+ type: object
2743
+ required: [schemaVersion, items, pagination]
2744
+ properties:
2745
+ schemaVersion:
2746
+ type: string
2747
+ description: Version of the `campaign_engagement_daily` row schema. Pin your ingest pipeline to this.
2748
+ example: '1.0'
2749
+ items:
2750
+ type: array
2751
+ items:
2752
+ $ref: '#/components/schemas/EngagementRow'
2753
+ pagination:
2754
+ $ref: '#/components/schemas/Pagination'
2755
+ meta:
2756
+ $ref: '#/components/schemas/Meta'
2757
+
2355
2758
  # --- Engagement ---
2356
2759
 
2357
2760
  EngagementRow:
@@ -2600,12 +3003,14 @@ components:
2600
3003
 
2601
3004
  SoundlinkMetricsOverview:
2602
3005
  type: object
2603
- description: Soundlink-level totals for the requested date range.
3006
+ description: |
3007
+ Soundlink-level totals for the requested date range. Additive fields
3008
+ are sums of `api_smart_link_country_daily` country-day rows.
2604
3009
  required: [views, streams, listeners, followers, streams_per_listener]
2605
3010
  properties:
2606
3011
  views:
2607
3012
  type: integer
2608
- description: Soundlink landing page views in the period.
3013
+ description: Soundlink landing page views in the period (sum of country-day rows).
2609
3014
  link_clicks:
2610
3015
  type: integer
2611
3016
  nullable: true
@@ -2614,26 +3019,13 @@ components:
2614
3019
  clicks to Spotify. Null if not tracked for this soundlink type.
2615
3020
  streams:
2616
3021
  type: integer
2617
- description: Attributed Spotify streams (sum of daily rows).
3022
+ description: Attributed Spotify streams (sum of country-day rows).
2618
3023
  listeners:
2619
3024
  type: integer
2620
- description: Unique attributed Spotify listeners in the period.
2621
- new_listeners:
2622
- type: integer
2623
- nullable: true
2624
- description: Unique listeners whose first play via this soundlink occurred in the period.
2625
- returning_listeners:
2626
- type: integer
2627
- nullable: true
2628
- description: Unique listeners who played in the period but whose first play was earlier.
2629
- new_listener_streams:
2630
- type: integer
2631
- nullable: true
2632
- description: Stream count from new listeners in the period.
2633
- returning_listener_streams:
2634
- type: integer
2635
- nullable: true
2636
- description: Stream count from returning listeners in the period.
3025
+ description: |
3026
+ Sum of country-day `new_listeners` from the mart (first-play
3027
+ attributed listeners). Not period-unique across days/countries,
3028
+ and not equal to summing breakdown `listeners` (new + returning).
2637
3029
  followers:
2638
3030
  type: integer
2639
3031
  description: Attributed Spotify artist follower gains in the period.
@@ -2805,31 +3197,156 @@ components:
2805
3197
  meta:
2806
3198
  $ref: '#/components/schemas/Meta'
2807
3199
 
2808
- SoundlinkEngagementItem:
3200
+ SoundlinkCountryDailyRow:
2809
3201
  type: object
2810
3202
  description: |
2811
- One track aggregated over the requested date range (period totals,
2812
- not daily rows).
2813
- required: [trackId, trackName, totalStreams, totalListeners, streamsPerListener]
3203
+ One row of the `soundlink_country_daily` v1.0 schema.
3204
+ Primary key: `(provider, account_id, report_date, soundlink_id, country_code)`.
3205
+ Rows are idempotent — re-ingesting on the primary key is safe.
3206
+ Values for a given `report_date` may be revised for up to 7 days after
3207
+ the date closes due to delayed Spotify playback events.
3208
+ Rows contain no financial fields.
3209
+ required:
3210
+ - provider
3211
+ - account_id
3212
+ - schema_version
3213
+ - report_date
3214
+ - report_date_timezone
3215
+ - exported_at
3216
+ - soundlink_id
3217
+ - soundlink_name
3218
+ - soundlink_target_type
3219
+ - country_code
3220
+ - views
3221
+ - streams
3222
+ - listeners
3223
+ - followers
3224
+ - streams_per_listener
2814
3225
  properties:
2815
- trackId:
3226
+ provider:
2816
3227
  type: string
2817
- description: Spotify track ID of the engaged track.
2818
- example: 4cOdK2wGLETKBW3PvgPWqT
2819
- trackName:
3228
+ enum: [soundlink]
3229
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
3230
+ account_id:
2820
3231
  type: string
2821
- description: Display name of the engaged track.
2822
- totalStreams:
3232
+ description: Soundlink organization ID (UUID).
3233
+ schema_version:
3234
+ type: string
3235
+ description: Schema version. Pin your ingest pipeline to this value.
3236
+ example: '1.0'
3237
+ report_date:
3238
+ type: string
3239
+ format: date
3240
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
3241
+ report_date_timezone:
3242
+ type: string
3243
+ enum: [UTC]
3244
+ description: Always `UTC`.
3245
+ exported_at:
3246
+ type: string
3247
+ format: date-time
3248
+ description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
3249
+ soundlink_id:
3250
+ type: string
3251
+ description: Unique ID of this soundlink.
3252
+ example: V1StGXR8_Z5jdHi6B-myT
3253
+ soundlink_name:
3254
+ type: string
3255
+ description: Human-readable soundlink name.
3256
+ soundlink_target_type:
3257
+ type: string
3258
+ nullable: true
3259
+ enum: [track, playlist]
3260
+ description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
3261
+ soundlink_target_isrc:
3262
+ type: string
3263
+ nullable: true
3264
+ description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3265
+ soundlink_target_spotify_track_id:
3266
+ type: string
3267
+ nullable: true
3268
+ description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3269
+ soundlink_target_playlist_id:
3270
+ type: string
3271
+ nullable: true
3272
+ description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
3273
+ country_code:
3274
+ type: string
3275
+ description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
3276
+ views:
2823
3277
  type: integer
2824
- minimum: 0
2825
- description: Total streams of this track in the period.
2826
- totalListeners:
3278
+ description: Soundlink landing page views in this country on this day.
3279
+ link_clicks:
2827
3280
  type: integer
2828
- minimum: 0
2829
- description: Unique listeners of this track in the period.
2830
- streamsPerListener:
3281
+ nullable: true
3282
+ description: |
3283
+ Clicks on "Continue with Spotify" on the landing page — outbound
3284
+ clicks to Spotify. Null if not tracked for this soundlink type.
3285
+ streams:
3286
+ type: integer
3287
+ description: |
3288
+ Spotify streams attributed to this soundlink in this country on this
3289
+ day: `new_listener_streams + returning_listener_streams`. Observed
3290
+ Spotify-side events, not modelled estimates. Safe to sum within a
3291
+ day; summing across days counts repeat listens.
3292
+ listeners:
3293
+ type: integer
3294
+ description: |
3295
+ Unique Spotify listeners attributed to this soundlink in this
3296
+ country on this day: `new_listeners + returning_listeners`.
3297
+ **Do not sum across days** — the same listener can appear on
3298
+ multiple `report_date` rows.
3299
+ new_listeners:
3300
+ type: integer
3301
+ nullable: true
3302
+ description: Unique listeners whose first play via this soundlink occurred on `report_date` in this country.
3303
+ returning_listeners:
3304
+ type: integer
3305
+ nullable: true
3306
+ description: Unique listeners who played on `report_date` in this country but whose first play was on an earlier date.
3307
+ new_listener_streams:
3308
+ type: integer
3309
+ nullable: true
3310
+ description: Stream count from new listeners on `report_date` in this country.
3311
+ returning_listener_streams:
3312
+ type: integer
3313
+ nullable: true
3314
+ description: Stream count from returning listeners on `report_date` in this country.
3315
+ followers:
3316
+ type: integer
3317
+ description: Spotify artist follower gains attributed to this soundlink in this country on this day.
3318
+ streams_per_listener:
2831
3319
  type: number
2832
- description: totalStreams / totalListeners. Zero if totalListeners is zero.
3320
+ description: streams / listeners for this row. Zero if listeners is zero.
3321
+ ctr_lp:
3322
+ type: number
3323
+ nullable: true
3324
+ description: |
3325
+ Landing page click-through rate (link_clicks / views). Computed
3326
+ against landing page views, not ad impressions — do not combine
3327
+ with `ctr_linkclick` from `campaign_country_daily`. Null if views
3328
+ is zero or link_clicks is null.
3329
+
3330
+ SoundlinkBreakdownResponse:
3331
+ type: object
3332
+ required: [data, meta]
3333
+ properties:
3334
+ data:
3335
+ type: object
3336
+ required: [schemaVersion, items, pagination]
3337
+ properties:
3338
+ schemaVersion:
3339
+ type: string
3340
+ description: Version of the `soundlink_country_daily` row schema. Pin your ingest pipeline to this.
3341
+ example: '1.0'
3342
+ items:
3343
+ type: array
3344
+ items:
3345
+ $ref: '#/components/schemas/SoundlinkCountryDailyRow'
3346
+ pagination:
3347
+ $ref: '#/components/schemas/Pagination'
3348
+ meta:
3349
+ $ref: '#/components/schemas/Meta'
2833
3350
 
2834
3351
  SoundlinkEngagementResponse:
2835
3352
  type: object
@@ -2837,17 +3354,163 @@ components:
2837
3354
  properties:
2838
3355
  data:
2839
3356
  type: object
2840
- required: [items, pagination]
3357
+ required: [schemaVersion, items, pagination]
2841
3358
  properties:
3359
+ schemaVersion:
3360
+ type: string
3361
+ description: Version of the `soundlink_engagement_daily` row schema. Pin your ingest pipeline to this.
3362
+ example: '1.0'
2842
3363
  items:
2843
3364
  type: array
2844
3365
  items:
2845
- $ref: '#/components/schemas/SoundlinkEngagementItem'
3366
+ $ref: '#/components/schemas/SoundlinkEngagementDailyRow'
2846
3367
  pagination:
2847
3368
  $ref: '#/components/schemas/Pagination'
2848
3369
  meta:
2849
3370
  $ref: '#/components/schemas/Meta'
2850
3371
 
3372
+ SoundlinkEngagementDailyRow:
3373
+ type: object
3374
+ description: |
3375
+ One row of the `soundlink_engagement_daily` v1.0 schema.
3376
+ Primary key: `(provider, account_id, report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
3377
+ Rows are idempotent — re-ingesting on the primary key is safe.
3378
+ Values for a given `report_date` may be revised for up to 7 days after
3379
+ the date closes due to delayed Spotify playback events.
3380
+ No `status` field: soundlinks do not store per-day lifecycle history.
3381
+ No financial fields.
3382
+ required:
3383
+ - provider
3384
+ - account_id
3385
+ - schema_version
3386
+ - report_date
3387
+ - report_date_timezone
3388
+ - exported_at
3389
+ - soundlink_id
3390
+ - soundlink_name
3391
+ - soundlink_target_type
3392
+ - engagement_context
3393
+ - country_code
3394
+ - engaged_spotify_track_id
3395
+ - engaged_track_name
3396
+ - new_listeners
3397
+ - returning_listeners
3398
+ - listeners
3399
+ - new_listener_streams
3400
+ - returning_listener_streams
3401
+ - streams
3402
+ - spl
3403
+ properties:
3404
+ provider:
3405
+ type: string
3406
+ enum: [soundlink]
3407
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
3408
+ account_id:
3409
+ type: string
3410
+ description: Soundlink organization ID (UUID).
3411
+ schema_version:
3412
+ type: string
3413
+ description: Schema version string. Pin your ingest pipeline to this value.
3414
+ example: '1.0'
3415
+ report_date:
3416
+ type: string
3417
+ format: date
3418
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`). Rows can change for up to 7 days after close.
3419
+ report_date_timezone:
3420
+ type: string
3421
+ enum: [UTC]
3422
+ description: Always `UTC`.
3423
+ exported_at:
3424
+ type: string
3425
+ format: date-time
3426
+ description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
3427
+ soundlink_id:
3428
+ type: string
3429
+ description: Unique ID of this soundlink.
3430
+ example: V1StGXR8_Z5jdHi6B-myT
3431
+ soundlink_name:
3432
+ type: string
3433
+ description: Human-readable soundlink name.
3434
+ soundlink_target_type:
3435
+ type: string
3436
+ nullable: true
3437
+ enum: [track, playlist]
3438
+ description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
3439
+ soundlink_target_isrc:
3440
+ type: string
3441
+ nullable: true
3442
+ description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3443
+ soundlink_target_spotify_track_id:
3444
+ type: string
3445
+ nullable: true
3446
+ description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
3447
+ soundlink_target_playlist_id:
3448
+ type: string
3449
+ nullable: true
3450
+ description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
3451
+ engagement_context:
3452
+ type: string
3453
+ enum: [catalog, playlist]
3454
+ description: |
3455
+ Which section this row belongs to.
3456
+ `catalog`: plays of the promoted track and same-artist catalog tracks (track soundlinks).
3457
+ `playlist`: per-track performance inside the promoted playlist (playlist soundlinks).
3458
+ country_code:
3459
+ type: string
3460
+ description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
3461
+ example: US
3462
+ engaged_track_isrc:
3463
+ type: string
3464
+ nullable: true
3465
+ description: |
3466
+ ISRC of the track that received listens. May differ from `soundlink_target_isrc`
3467
+ for catalog spillover rows. `null` if ISRC could not be resolved.
3468
+ engaged_spotify_track_id:
3469
+ type: string
3470
+ description: Spotify track ID of the engaged track. Part of the primary key.
3471
+ example: 4cOdK2wGLETKBW3PvgPWqT
3472
+ engaged_track_name:
3473
+ type: string
3474
+ description: Display name of the engaged track.
3475
+ playlist_position:
3476
+ type: integer
3477
+ nullable: true
3478
+ minimum: 1
3479
+ description: |
3480
+ 1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
3481
+ Populated only when `engagement_context = playlist`. Treat `null` as unavailable, not an error.
3482
+ new_listeners:
3483
+ type: integer
3484
+ minimum: 0
3485
+ description: Unique listeners whose first play of this track via this soundlink occurred on `report_date`.
3486
+ returning_listeners:
3487
+ type: integer
3488
+ minimum: 0
3489
+ description: Unique listeners who played this track on `report_date` but whose first play was on an earlier date.
3490
+ listeners:
3491
+ type: integer
3492
+ minimum: 0
3493
+ description: |
3494
+ Total unique listeners on `report_date`: `new_listeners + returning_listeners`.
3495
+ **Do not sum across days** — the same listener can appear on multiple `report_date` rows.
3496
+ new_listener_streams:
3497
+ type: integer
3498
+ minimum: 0
3499
+ description: Stream count from new listeners on `report_date`.
3500
+ returning_listener_streams:
3501
+ type: integer
3502
+ minimum: 0
3503
+ description: Stream count from returning listeners on `report_date`.
3504
+ streams:
3505
+ type: integer
3506
+ minimum: 0
3507
+ description: |
3508
+ Total streams on `report_date`: `new_listener_streams + returning_listener_streams`.
3509
+ Safe to sum within a day; summing across days counts repeat listens.
3510
+ spl:
3511
+ type: number
3512
+ description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
3513
+
2851
3514
  # --- Videos ---
2852
3515
 
2853
3516
  VideoImportRequest: