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.
- package/CHANGELOG.md +11 -0
- package/README.md +5 -5
- package/dist/cjs/index.cjs +61 -17
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +117 -67
- package/dist/esm/index.js +61 -17
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +825 -162
- package/package.json +1 -1
|
@@ -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
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
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:
|
|
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:
|
|
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`
|
|
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/
|
|
1307
|
+
/v1/soundlinks/{soundlinkId}/metrics/breakdown:
|
|
1198
1308
|
get:
|
|
1199
|
-
operationId:
|
|
1200
|
-
summary: Soundlink
|
|
1309
|
+
operationId: getSoundlinkMetricsBreakdown
|
|
1310
|
+
summary: Soundlink metrics breakdown
|
|
1201
1311
|
description: |
|
|
1202
|
-
|
|
1203
|
-
|
|
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
|
-
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
|
|
1210
|
-
|
|
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/
|
|
1339
|
+
- $ref: '#/components/parameters/soundlinkStartDate'
|
|
1221
1340
|
- $ref: '#/components/parameters/soundlinkEndDate'
|
|
1222
1341
|
- $ref: '#/components/parameters/page'
|
|
1223
|
-
- $ref: '#/components/parameters/
|
|
1342
|
+
- $ref: '#/components/parameters/pageSize500'
|
|
1224
1343
|
- name: sortBy
|
|
1225
1344
|
in: query
|
|
1226
1345
|
schema:
|
|
1227
1346
|
type: string
|
|
1228
|
-
enum: [
|
|
1229
|
-
default:
|
|
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
|
|
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/
|
|
1356
|
+
$ref: '#/components/schemas/SoundlinkBreakdownResponse'
|
|
1238
1357
|
example:
|
|
1239
1358
|
data:
|
|
1359
|
+
schemaVersion: '1.0'
|
|
1240
1360
|
items:
|
|
1241
|
-
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
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:
|
|
1254
|
-
totalCount:
|
|
1255
|
-
totalPages:
|
|
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/
|
|
1266
|
-
|
|
1267
|
-
operationId:
|
|
1268
|
-
summary:
|
|
1399
|
+
/v1/soundlinks/{soundlinkId}/metrics/breakdown/export:
|
|
1400
|
+
get:
|
|
1401
|
+
operationId: exportSoundlinkMetricsBreakdown
|
|
1402
|
+
summary: Soundlink metrics breakdown export (JSONL)
|
|
1269
1403
|
description: |
|
|
1270
|
-
|
|
1271
|
-
|
|
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
|
-
|
|
1274
|
-
|
|
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
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
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:
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
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:
|
|
1306
|
-
|
|
1307
|
-
|
|
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
|
-
|
|
1310
|
-
|
|
1311
|
-
|
|
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/
|
|
1456
|
+
application/x-ndjson:
|
|
1314
1457
|
schema:
|
|
1315
|
-
$ref: '#/components/schemas/
|
|
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/
|
|
1469
|
+
/v1/soundlinks/{soundlinkId}/metrics/engagement:
|
|
1323
1470
|
get:
|
|
1324
|
-
operationId:
|
|
1325
|
-
summary:
|
|
1471
|
+
operationId: getSoundlinkEngagement
|
|
1472
|
+
summary: Soundlink engagement breakdown
|
|
1326
1473
|
description: |
|
|
1327
|
-
|
|
1328
|
-
|
|
1329
|
-
|
|
1330
|
-
|
|
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:
|
|
1510
|
+
x-required-scope: soundlinks:read
|
|
1335
1511
|
parameters:
|
|
1336
|
-
-
|
|
1337
|
-
|
|
1338
|
-
|
|
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
|
-
|
|
1342
|
-
description:
|
|
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:
|
|
1532
|
+
description: Paginated engagement rows (`soundlink_engagement_daily` schema)
|
|
1346
1533
|
content:
|
|
1347
1534
|
application/json:
|
|
1348
1535
|
schema:
|
|
1349
|
-
$ref: '#/components/schemas/
|
|
1350
|
-
|
|
1351
|
-
|
|
1352
|
-
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
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:
|
|
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
|
|
3022
|
+
description: Attributed Spotify streams (sum of country-day rows).
|
|
2618
3023
|
listeners:
|
|
2619
3024
|
type: integer
|
|
2620
|
-
description:
|
|
2621
|
-
|
|
2622
|
-
|
|
2623
|
-
|
|
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
|
-
|
|
3200
|
+
SoundlinkCountryDailyRow:
|
|
2809
3201
|
type: object
|
|
2810
3202
|
description: |
|
|
2811
|
-
One
|
|
2812
|
-
|
|
2813
|
-
|
|
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
|
-
|
|
3226
|
+
provider:
|
|
2816
3227
|
type: string
|
|
2817
|
-
|
|
2818
|
-
|
|
2819
|
-
|
|
3228
|
+
enum: [soundlink]
|
|
3229
|
+
description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
|
|
3230
|
+
account_id:
|
|
2820
3231
|
type: string
|
|
2821
|
-
description:
|
|
2822
|
-
|
|
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
|
-
|
|
2825
|
-
|
|
2826
|
-
totalListeners:
|
|
3278
|
+
description: Soundlink landing page views in this country on this day.
|
|
3279
|
+
link_clicks:
|
|
2827
3280
|
type: integer
|
|
2828
|
-
|
|
2829
|
-
description:
|
|
2830
|
-
|
|
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:
|
|
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/
|
|
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:
|