soundlink 2.1.0 → 2.3.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 +17 -0
- package/README.md +18 -7
- package/dist/cjs/index.cjs +112 -18
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +165 -71
- package/dist/esm/index.js +112 -18
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +1033 -151
- package/package.json +2 -2
|
@@ -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.
|
|
@@ -1011,6 +1123,80 @@ paths:
|
|
|
1011
1123
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1012
1124
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
1013
1125
|
|
|
1126
|
+
post:
|
|
1127
|
+
operationId: createSoundlink
|
|
1128
|
+
summary: Create a self-serve soundlink
|
|
1129
|
+
description: |
|
|
1130
|
+
Creates a self-serve soundlink in the organization. This is the Public
|
|
1131
|
+
API equivalent of the in-app create flow. It does not create a wallet
|
|
1132
|
+
campaign and does not appear on `GET /v1/campaigns`.
|
|
1133
|
+
|
|
1134
|
+
Requires the `soundlinks:write` scope.
|
|
1135
|
+
|
|
1136
|
+
`Idempotency-Key` is **required**. Reusing the key with an unchanged
|
|
1137
|
+
body replays the original `201`; a different body returns
|
|
1138
|
+
`409 idempotency_key_conflict`. Keys are honored for 24 hours.
|
|
1139
|
+
|
|
1140
|
+
**Auth:** Accepts API key or OAuth Bearer (`soundlinks:write`).
|
|
1141
|
+
tags: [Soundlinks]
|
|
1142
|
+
security:
|
|
1143
|
+
- apiKeyBearerAuth: []
|
|
1144
|
+
- oauthBearer: []
|
|
1145
|
+
x-required-scope: soundlinks:write
|
|
1146
|
+
parameters:
|
|
1147
|
+
- $ref: '#/components/parameters/idempotencyKey'
|
|
1148
|
+
requestBody:
|
|
1149
|
+
required: true
|
|
1150
|
+
content:
|
|
1151
|
+
application/json:
|
|
1152
|
+
schema:
|
|
1153
|
+
$ref: '#/components/schemas/CreateSoundlinkRequest'
|
|
1154
|
+
examples:
|
|
1155
|
+
track:
|
|
1156
|
+
summary: Track soundlink
|
|
1157
|
+
value:
|
|
1158
|
+
name: Midnight Drive
|
|
1159
|
+
spotifyUrl: 'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl'
|
|
1160
|
+
autoFollow: true
|
|
1161
|
+
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1162
|
+
metaPixelId: '1234567890123456'
|
|
1163
|
+
metaConversionAccessToken: 'EAAB...'
|
|
1164
|
+
playlist:
|
|
1165
|
+
summary: Playlist soundlink
|
|
1166
|
+
value:
|
|
1167
|
+
name: Late Night Mix
|
|
1168
|
+
spotifyUrl: 'https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M'
|
|
1169
|
+
responses:
|
|
1170
|
+
'201':
|
|
1171
|
+
description: Soundlink created
|
|
1172
|
+
content:
|
|
1173
|
+
application/json:
|
|
1174
|
+
schema:
|
|
1175
|
+
$ref: '#/components/schemas/SoundlinkDetailResponse'
|
|
1176
|
+
example:
|
|
1177
|
+
data:
|
|
1178
|
+
soundlinkId: V1StGXR8_Z5jdHi6B-myT
|
|
1179
|
+
organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1180
|
+
name: Midnight Drive
|
|
1181
|
+
url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
|
|
1182
|
+
targetType: track
|
|
1183
|
+
spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
|
|
1184
|
+
status: active
|
|
1185
|
+
createdAt: '2026-04-01T10:00:00Z'
|
|
1186
|
+
autoFollow: true
|
|
1187
|
+
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1188
|
+
metaPixelId: '1234567890123456'
|
|
1189
|
+
tiktokPixelId: null
|
|
1190
|
+
meta:
|
|
1191
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1192
|
+
'400': { $ref: '#/components/responses/CreateSoundlinkBadRequest' }
|
|
1193
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1194
|
+
'403': { $ref: '#/components/responses/CreateSoundlinkForbidden' }
|
|
1195
|
+
'409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
|
|
1196
|
+
'422': { $ref: '#/components/responses/CreateSoundlinkUnprocessable' }
|
|
1197
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1198
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1199
|
+
|
|
1014
1200
|
/v1/soundlinks/{soundlinkId}:
|
|
1015
1201
|
get:
|
|
1016
1202
|
operationId: getSoundlink
|
|
@@ -1045,6 +1231,55 @@ paths:
|
|
|
1045
1231
|
status: active
|
|
1046
1232
|
createdAt: '2026-04-01T10:00:00Z'
|
|
1047
1233
|
autoFollow: true
|
|
1234
|
+
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1235
|
+
metaPixelId: '1234567890123456'
|
|
1236
|
+
tiktokPixelId: null
|
|
1237
|
+
meta:
|
|
1238
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1239
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1240
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1241
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1242
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1243
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1244
|
+
|
|
1245
|
+
delete:
|
|
1246
|
+
operationId: archiveSoundlink
|
|
1247
|
+
summary: Archive a soundlink
|
|
1248
|
+
description: |
|
|
1249
|
+
Archives a self-serve soundlink (`status: archived`). Same as Archive
|
|
1250
|
+
in the app: the public landing page returns 404 after cache expires.
|
|
1251
|
+
List and detail still return the row. Cannot be undone via the Public
|
|
1252
|
+
API.
|
|
1253
|
+
|
|
1254
|
+
Requires `soundlinks:write`. Campaign-linked soundlinks, soundlinks
|
|
1255
|
+
that are not `active`, and ids that do not belong to the org return
|
|
1256
|
+
`404`. Does not require `Idempotency-Key`.
|
|
1257
|
+
tags: [Soundlinks]
|
|
1258
|
+
security:
|
|
1259
|
+
- apiKeyBearerAuth: []
|
|
1260
|
+
- oauthBearer: []
|
|
1261
|
+
x-required-scope: soundlinks:write
|
|
1262
|
+
parameters:
|
|
1263
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1264
|
+
responses:
|
|
1265
|
+
'200':
|
|
1266
|
+
description: Soundlink archived
|
|
1267
|
+
content:
|
|
1268
|
+
application/json:
|
|
1269
|
+
schema:
|
|
1270
|
+
$ref: '#/components/schemas/SoundlinkDetailResponse'
|
|
1271
|
+
example:
|
|
1272
|
+
data:
|
|
1273
|
+
soundlinkId: V1StGXR8_Z5jdHi6B-myT
|
|
1274
|
+
organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1275
|
+
name: Midnight Drive
|
|
1276
|
+
url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
|
|
1277
|
+
targetType: track
|
|
1278
|
+
spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
|
|
1279
|
+
status: archived
|
|
1280
|
+
createdAt: '2026-04-01T10:00:00Z'
|
|
1281
|
+
autoFollow: true
|
|
1282
|
+
artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
|
|
1048
1283
|
metaPixelId: '1234567890123456'
|
|
1049
1284
|
tiktokPixelId: null
|
|
1050
1285
|
meta:
|
|
@@ -1061,10 +1296,12 @@ paths:
|
|
|
1061
1296
|
summary: Soundlink metrics overview
|
|
1062
1297
|
description: |
|
|
1063
1298
|
Soundlink-level totals for a date range: landing page views, outbound
|
|
1064
|
-
clicks, listeners
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1299
|
+
clicks, listeners, streams, followers, and derived ratios. Totals are
|
|
1300
|
+
sums of country-day mart rows (`api_smart_link_country_daily`);
|
|
1301
|
+
`listeners` is the sum of daily country `new_listeners` (not
|
|
1302
|
+
period-unique). No per-day rows — use `/metrics/timeseries` for those,
|
|
1303
|
+
or `/metrics/breakdown` for country-day rows (including new/returning
|
|
1304
|
+
splits).
|
|
1068
1305
|
|
|
1069
1306
|
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1070
1307
|
tags: [Soundlinks]
|
|
@@ -1088,13 +1325,9 @@ paths:
|
|
|
1088
1325
|
views: 4821
|
|
1089
1326
|
link_clicks: 890
|
|
1090
1327
|
streams: 9340
|
|
1091
|
-
listeners:
|
|
1092
|
-
new_listeners: 3980
|
|
1093
|
-
returning_listeners: 841
|
|
1094
|
-
new_listener_streams: 7104
|
|
1095
|
-
returning_listener_streams: 2236
|
|
1328
|
+
listeners: 3980
|
|
1096
1329
|
followers: 312
|
|
1097
|
-
streams_per_listener:
|
|
1330
|
+
streams_per_listener: 2.35
|
|
1098
1331
|
ctr_lp: 0.185
|
|
1099
1332
|
meta:
|
|
1100
1333
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
@@ -1121,11 +1354,276 @@ paths:
|
|
|
1121
1354
|
for up to 7 days after the date closes due to delayed Spotify playback
|
|
1122
1355
|
events. Re-fetch or re-ingest accordingly.
|
|
1123
1356
|
|
|
1124
|
-
Rows are aggregated across countries (no `country_code`
|
|
1125
|
-
contain no financial fields.
|
|
1357
|
+
Rows are aggregated across countries (no `country_code`) and
|
|
1358
|
+
contain no financial fields. For country-day rows use
|
|
1359
|
+
`/metrics/breakdown` (and `/metrics/breakdown/export`).
|
|
1360
|
+
|
|
1361
|
+
Maps to the **Trends** tab in the Soundlink Insights UI.
|
|
1362
|
+
|
|
1363
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1364
|
+
tags: [Soundlinks]
|
|
1365
|
+
security:
|
|
1366
|
+
- apiKeyBearerAuth: []
|
|
1367
|
+
- oauthBearer: []
|
|
1368
|
+
x-required-scope: soundlinks:read
|
|
1369
|
+
parameters:
|
|
1370
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1371
|
+
- $ref: '#/components/parameters/soundlinkStartDate'
|
|
1372
|
+
- $ref: '#/components/parameters/soundlinkEndDate'
|
|
1373
|
+
- $ref: '#/components/parameters/page'
|
|
1374
|
+
- $ref: '#/components/parameters/pageSize500'
|
|
1375
|
+
- name: sortBy
|
|
1376
|
+
in: query
|
|
1377
|
+
schema:
|
|
1378
|
+
type: string
|
|
1379
|
+
enum: [report_date]
|
|
1380
|
+
default: report_date
|
|
1381
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
1382
|
+
responses:
|
|
1383
|
+
'200':
|
|
1384
|
+
description: Paginated per-day rows (`soundlink_daily` schema)
|
|
1385
|
+
content:
|
|
1386
|
+
application/json:
|
|
1387
|
+
schema:
|
|
1388
|
+
$ref: '#/components/schemas/SoundlinkTimeseriesResponse'
|
|
1389
|
+
example:
|
|
1390
|
+
data:
|
|
1391
|
+
schemaVersion: '1.0'
|
|
1392
|
+
items:
|
|
1393
|
+
- provider: soundlink
|
|
1394
|
+
account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1395
|
+
schema_version: '1.0'
|
|
1396
|
+
report_date: '2026-08-01'
|
|
1397
|
+
report_date_timezone: UTC
|
|
1398
|
+
exported_at: '2026-08-28T03:00:00Z'
|
|
1399
|
+
soundlink_id: V1StGXR8_Z5jdHi6B-myT
|
|
1400
|
+
soundlink_name: Midnight Drive
|
|
1401
|
+
soundlink_target_type: track
|
|
1402
|
+
soundlink_target_isrc: DEXW62500259
|
|
1403
|
+
soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
1404
|
+
soundlink_target_playlist_id: null
|
|
1405
|
+
views: 4821
|
|
1406
|
+
link_clicks: 890
|
|
1407
|
+
streams: 203
|
|
1408
|
+
listeners: 145
|
|
1409
|
+
new_listeners: 120
|
|
1410
|
+
returning_listeners: 25
|
|
1411
|
+
new_listener_streams: 160
|
|
1412
|
+
returning_listener_streams: 43
|
|
1413
|
+
followers: 12
|
|
1414
|
+
streams_per_listener: 1.4
|
|
1415
|
+
ctr_lp: 0.185
|
|
1416
|
+
pagination:
|
|
1417
|
+
page: 1
|
|
1418
|
+
pageSize: 50
|
|
1419
|
+
totalCount: 90
|
|
1420
|
+
totalPages: 2
|
|
1421
|
+
meta:
|
|
1422
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1423
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1424
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1425
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1426
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1427
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1428
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1429
|
+
|
|
1430
|
+
/v1/soundlinks/{soundlinkId}/metrics/breakdown:
|
|
1431
|
+
get:
|
|
1432
|
+
operationId: getSoundlinkMetricsBreakdown
|
|
1433
|
+
summary: Soundlink metrics breakdown
|
|
1434
|
+
description: |
|
|
1435
|
+
Per-day metrics broken down by country. One row per
|
|
1436
|
+
`(report_date, soundlink_id, country_code)`. Can be large, so results
|
|
1437
|
+
are paginated.
|
|
1438
|
+
|
|
1439
|
+
**Row schema:** `soundlink_country_daily` v1.0 — the same schema used
|
|
1440
|
+
in JSONL bulk exports. Rows are idempotent on the primary key
|
|
1441
|
+
`(provider, account_id, report_date, soundlink_id, country_code)`;
|
|
1442
|
+
re-ingesting is safe.
|
|
1443
|
+
|
|
1444
|
+
**Mutability window:** rows for a given `report_date` can be revised
|
|
1445
|
+
for up to 7 days after the date closes due to delayed Spotify playback
|
|
1446
|
+
events. Re-fetch or re-ingest accordingly.
|
|
1447
|
+
|
|
1448
|
+
Rows contain no financial fields: ads for self-serve soundlinks run
|
|
1449
|
+
in your own Meta account, so spend is not visible to Soundlink.
|
|
1450
|
+
|
|
1451
|
+
Maps to the **Countries** tab in the Soundlink Insights UI.
|
|
1452
|
+
Use `/metrics/timeseries` for country-aggregated daily Trends rows.
|
|
1453
|
+
|
|
1454
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1455
|
+
tags: [Soundlinks]
|
|
1456
|
+
security:
|
|
1457
|
+
- apiKeyBearerAuth: []
|
|
1458
|
+
- oauthBearer: []
|
|
1459
|
+
x-required-scope: soundlinks:read
|
|
1460
|
+
parameters:
|
|
1461
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1462
|
+
- $ref: '#/components/parameters/soundlinkStartDate'
|
|
1463
|
+
- $ref: '#/components/parameters/soundlinkEndDate'
|
|
1464
|
+
- $ref: '#/components/parameters/page'
|
|
1465
|
+
- $ref: '#/components/parameters/pageSize500'
|
|
1466
|
+
- name: sortBy
|
|
1467
|
+
in: query
|
|
1468
|
+
schema:
|
|
1469
|
+
type: string
|
|
1470
|
+
enum: [report_date, country_code]
|
|
1471
|
+
default: report_date
|
|
1472
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
1473
|
+
responses:
|
|
1474
|
+
'200':
|
|
1475
|
+
description: Paginated per-day country rows (`soundlink_country_daily` schema)
|
|
1476
|
+
content:
|
|
1477
|
+
application/json:
|
|
1478
|
+
schema:
|
|
1479
|
+
$ref: '#/components/schemas/SoundlinkBreakdownResponse'
|
|
1480
|
+
example:
|
|
1481
|
+
data:
|
|
1482
|
+
schemaVersion: '1.0'
|
|
1483
|
+
items:
|
|
1484
|
+
- provider: soundlink
|
|
1485
|
+
account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1486
|
+
schema_version: '1.0'
|
|
1487
|
+
report_date: '2026-08-01'
|
|
1488
|
+
report_date_timezone: UTC
|
|
1489
|
+
exported_at: '2026-08-28T03:00:00Z'
|
|
1490
|
+
soundlink_id: V1StGXR8_Z5jdHi6B-myT
|
|
1491
|
+
soundlink_name: Midnight Drive
|
|
1492
|
+
soundlink_target_type: track
|
|
1493
|
+
soundlink_target_isrc: DEXW62500259
|
|
1494
|
+
soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
1495
|
+
soundlink_target_playlist_id: null
|
|
1496
|
+
country_code: US
|
|
1497
|
+
views: 4821
|
|
1498
|
+
link_clicks: 890
|
|
1499
|
+
streams: 203
|
|
1500
|
+
listeners: 145
|
|
1501
|
+
new_listeners: 120
|
|
1502
|
+
returning_listeners: 25
|
|
1503
|
+
new_listener_streams: 160
|
|
1504
|
+
returning_listener_streams: 43
|
|
1505
|
+
followers: 12
|
|
1506
|
+
streams_per_listener: 1.4
|
|
1507
|
+
ctr_lp: 0.185
|
|
1508
|
+
pagination:
|
|
1509
|
+
page: 1
|
|
1510
|
+
pageSize: 50
|
|
1511
|
+
totalCount: 340
|
|
1512
|
+
totalPages: 7
|
|
1513
|
+
meta:
|
|
1514
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1515
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1516
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1517
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1518
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1519
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1520
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1521
|
+
|
|
1522
|
+
/v1/soundlinks/{soundlinkId}/metrics/breakdown/export:
|
|
1523
|
+
get:
|
|
1524
|
+
operationId: exportSoundlinkMetricsBreakdown
|
|
1525
|
+
summary: Soundlink metrics breakdown export (JSONL)
|
|
1526
|
+
description: |
|
|
1527
|
+
Streams the full country-level metrics dataset for a soundlink as
|
|
1528
|
+
**newline-delimited JSON (JSONL)**. Every line is a complete, valid
|
|
1529
|
+
JSON object conforming to the `soundlink_country_daily` v1.0 schema
|
|
1530
|
+
— identical to the rows returned by `GET /metrics/breakdown` but
|
|
1531
|
+
without pagination or an envelope wrapper.
|
|
1532
|
+
|
|
1533
|
+
Designed for data pipeline consumers: load directly into BigQuery,
|
|
1534
|
+
Snowflake, or any JSONL-aware ingest tool without cursor logic.
|
|
1535
|
+
|
|
1536
|
+
**Usage:**
|
|
1537
|
+
```
|
|
1538
|
+
GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export
|
|
1539
|
+
Accept: application/x-ndjson
|
|
1540
|
+
```
|
|
1541
|
+
|
|
1542
|
+
**Date range:** if you omit both dates, defaults to the last **90 days**
|
|
1543
|
+
ending today. Override with `startDate` / `endDate`. **Responses are
|
|
1544
|
+
capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
|
|
1545
|
+
Page longer histories in 90-day slices.
|
|
1546
|
+
|
|
1547
|
+
**Mutability:** rows for a given `report_date` can be revised for up
|
|
1548
|
+
to 7 days after the date closes due to delayed Spotify playback
|
|
1549
|
+
events. Re-fetching and re-ingesting on the primary key is safe
|
|
1550
|
+
(idempotent).
|
|
1551
|
+
|
|
1552
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1553
|
+
tags: [Soundlinks]
|
|
1554
|
+
security:
|
|
1555
|
+
- apiKeyBearerAuth: []
|
|
1556
|
+
- oauthBearer: []
|
|
1557
|
+
x-required-scope: soundlinks:read
|
|
1558
|
+
parameters:
|
|
1559
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1560
|
+
- $ref: '#/components/parameters/startDate'
|
|
1561
|
+
- $ref: '#/components/parameters/endDate'
|
|
1562
|
+
responses:
|
|
1563
|
+
'200':
|
|
1564
|
+
description: |
|
|
1565
|
+
JSONL stream. Each line is a `soundlink_country_daily` v1.0 row.
|
|
1566
|
+
Lines are sorted by `(report_date asc, country_code)`.
|
|
1567
|
+
headers:
|
|
1568
|
+
Content-Disposition:
|
|
1569
|
+
schema:
|
|
1570
|
+
type: string
|
|
1571
|
+
description: |
|
|
1572
|
+
`attachment; filename="breakdown_{soundlinkId}_{startDate}_{endDate}.jsonl"`
|
|
1573
|
+
example: 'attachment; filename="breakdown_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
|
|
1574
|
+
X-Row-Count:
|
|
1575
|
+
schema:
|
|
1576
|
+
type: integer
|
|
1577
|
+
description: Total number of rows in the response.
|
|
1578
|
+
content:
|
|
1579
|
+
application/x-ndjson:
|
|
1580
|
+
schema:
|
|
1581
|
+
$ref: '#/components/schemas/SoundlinkCountryDailyRow'
|
|
1582
|
+
example: |
|
|
1583
|
+
{"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}
|
|
1584
|
+
{"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}
|
|
1585
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1586
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1587
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1588
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1589
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1590
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1591
|
+
|
|
1592
|
+
/v1/soundlinks/{soundlinkId}/metrics/engagement:
|
|
1593
|
+
get:
|
|
1594
|
+
operationId: getSoundlinkEngagement
|
|
1595
|
+
summary: Soundlink engagement breakdown
|
|
1596
|
+
description: |
|
|
1597
|
+
Per-day, per-track engagement metrics for a soundlink. One row per
|
|
1598
|
+
`(report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
1599
|
+
Results are paginated.
|
|
1600
|
+
|
|
1601
|
+
**Row schema:** `soundlink_engagement_daily` v1.0 — the same schema used
|
|
1602
|
+
in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting
|
|
1603
|
+
is safe.
|
|
1604
|
+
|
|
1605
|
+
**Key difference from `/metrics/breakdown`:** breakdown aggregates
|
|
1606
|
+
views, streams, and listeners by **country** (`soundlink_country_daily`);
|
|
1607
|
+
engagement breaks down **which tracks** listeners played, including
|
|
1608
|
+
catalog spillover and playlist slot performance (`engagement_context`,
|
|
1609
|
+
`engaged_spotify_track_id`).
|
|
1610
|
+
|
|
1611
|
+
**`engagement_context` values:**
|
|
1612
|
+
- `catalog` — same-artist spillover (and direct promoted-track plays)
|
|
1613
|
+
on track soundlinks.
|
|
1614
|
+
- `playlist` — per-track performance inside the promoted playlist on
|
|
1615
|
+
playlist soundlinks.
|
|
1616
|
+
|
|
1617
|
+
**`listeners` is deduplicated within each row only.** Do not sum
|
|
1618
|
+
`listeners` across days to get a soundlink total.
|
|
1126
1619
|
|
|
1127
|
-
|
|
1128
|
-
|
|
1620
|
+
**Date range:** if you omit both dates, defaults to the last **90 days**
|
|
1621
|
+
ending today. Override with `startDate` / `endDate`. **Responses are
|
|
1622
|
+
capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
|
|
1623
|
+
|
|
1624
|
+
**Mutability window:** rows for a given `report_date` can be revised
|
|
1625
|
+
for up to 7 days after the date closes due to delayed Spotify
|
|
1626
|
+
playback events.
|
|
1129
1627
|
|
|
1130
1628
|
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1131
1629
|
tags: [Soundlinks]
|
|
@@ -1135,8 +1633,14 @@ paths:
|
|
|
1135
1633
|
x-required-scope: soundlinks:read
|
|
1136
1634
|
parameters:
|
|
1137
1635
|
- $ref: '#/components/parameters/soundlinkId'
|
|
1138
|
-
- $ref: '#/components/parameters/
|
|
1139
|
-
- $ref: '#/components/parameters/
|
|
1636
|
+
- $ref: '#/components/parameters/startDate'
|
|
1637
|
+
- $ref: '#/components/parameters/endDate'
|
|
1638
|
+
- name: engagementContext
|
|
1639
|
+
in: query
|
|
1640
|
+
schema:
|
|
1641
|
+
type: string
|
|
1642
|
+
enum: [catalog, playlist]
|
|
1643
|
+
description: Filter to a single engagement context. Omit to return both.
|
|
1140
1644
|
- $ref: '#/components/parameters/page'
|
|
1141
1645
|
- $ref: '#/components/parameters/pageSize500'
|
|
1142
1646
|
- name: sortBy
|
|
@@ -1148,11 +1652,11 @@ paths:
|
|
|
1148
1652
|
- $ref: '#/components/parameters/sortOrder'
|
|
1149
1653
|
responses:
|
|
1150
1654
|
'200':
|
|
1151
|
-
description: Paginated
|
|
1655
|
+
description: Paginated engagement rows (`soundlink_engagement_daily` schema)
|
|
1152
1656
|
content:
|
|
1153
1657
|
application/json:
|
|
1154
1658
|
schema:
|
|
1155
|
-
$ref: '#/components/schemas/
|
|
1659
|
+
$ref: '#/components/schemas/SoundlinkEngagementResponse'
|
|
1156
1660
|
example:
|
|
1157
1661
|
data:
|
|
1158
1662
|
schemaVersion: '1.0'
|
|
@@ -1169,22 +1673,24 @@ paths:
|
|
|
1169
1673
|
soundlink_target_isrc: DEXW62500259
|
|
1170
1674
|
soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
1171
1675
|
soundlink_target_playlist_id: null
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
|
|
1182
|
-
|
|
1676
|
+
engagement_context: catalog
|
|
1677
|
+
country_code: US
|
|
1678
|
+
engaged_track_isrc: DEXW62500001
|
|
1679
|
+
engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
|
|
1680
|
+
engaged_track_name: Till The Sunrise
|
|
1681
|
+
playlist_position: null
|
|
1682
|
+
new_listeners: 42
|
|
1683
|
+
returning_listeners: 18
|
|
1684
|
+
listeners: 60
|
|
1685
|
+
new_listener_streams: 58
|
|
1686
|
+
returning_listener_streams: 31
|
|
1687
|
+
streams: 89
|
|
1688
|
+
spl: 1.48
|
|
1183
1689
|
pagination:
|
|
1184
1690
|
page: 1
|
|
1185
1691
|
pageSize: 50
|
|
1186
|
-
totalCount:
|
|
1187
|
-
totalPages:
|
|
1692
|
+
totalCount: 120
|
|
1693
|
+
totalPages: 3
|
|
1188
1694
|
meta:
|
|
1189
1695
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1190
1696
|
'400': { $ref: '#/components/responses/BadRequest' }
|
|
@@ -1194,20 +1700,40 @@ paths:
|
|
|
1194
1700
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1195
1701
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
1196
1702
|
|
|
1197
|
-
/v1/soundlinks/{soundlinkId}/metrics/engagement:
|
|
1703
|
+
/v1/soundlinks/{soundlinkId}/metrics/engagement/export:
|
|
1198
1704
|
get:
|
|
1199
|
-
operationId:
|
|
1200
|
-
summary: Soundlink engagement (
|
|
1705
|
+
operationId: exportSoundlinkEngagement
|
|
1706
|
+
summary: Soundlink engagement export (JSONL)
|
|
1201
1707
|
description: |
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1708
|
+
Streams the full engagement dataset for a soundlink as
|
|
1709
|
+
**newline-delimited JSON (JSONL)**. Every line is a complete, valid
|
|
1710
|
+
JSON object conforming to the `soundlink_engagement_daily` v1.0 schema
|
|
1711
|
+
— identical to the rows returned by `GET /metrics/engagement` but
|
|
1712
|
+
without pagination or an envelope wrapper.
|
|
1713
|
+
|
|
1714
|
+
Designed for data pipeline consumers: load directly into BigQuery,
|
|
1715
|
+
Snowflake, or any JSONL-aware ingest tool without cursor logic.
|
|
1716
|
+
|
|
1717
|
+
**Usage:**
|
|
1718
|
+
```
|
|
1719
|
+
GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export
|
|
1720
|
+
Accept: application/x-ndjson
|
|
1721
|
+
```
|
|
1722
|
+
|
|
1723
|
+
**Response body (one JSON object per line, no trailing comma):**
|
|
1724
|
+
```
|
|
1725
|
+
{"provider":"soundlink","report_date":"2026-08-01","streams":89,...}
|
|
1726
|
+
{"provider":"soundlink","report_date":"2026-08-02","streams":104,...}
|
|
1727
|
+
```
|
|
1728
|
+
|
|
1729
|
+
**Date range:** if you omit both dates, defaults to the last **90 days**
|
|
1730
|
+
ending today. Override with `startDate` / `endDate`. **Responses are
|
|
1731
|
+
capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
|
|
1732
|
+
Page longer histories in 90-day slices.
|
|
1205
1733
|
|
|
1206
|
-
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
last 7 days (inclusive span ending today), or all-time. Omitting
|
|
1210
|
-
`startDate` always uses all-time (it is not inferred from createdAt).
|
|
1734
|
+
**Mutability:** rows for a given `report_date` can be revised for up to
|
|
1735
|
+
7 days after the date closes. Re-fetching and re-ingesting on the
|
|
1736
|
+
primary key is safe (idempotent).
|
|
1211
1737
|
|
|
1212
1738
|
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1213
1739
|
tags: [Soundlinks]
|
|
@@ -1217,44 +1743,37 @@ paths:
|
|
|
1217
1743
|
x-required-scope: soundlinks:read
|
|
1218
1744
|
parameters:
|
|
1219
1745
|
- $ref: '#/components/parameters/soundlinkId'
|
|
1220
|
-
- $ref: '#/components/parameters/
|
|
1221
|
-
- $ref: '#/components/parameters/
|
|
1222
|
-
-
|
|
1223
|
-
- $ref: '#/components/parameters/pageSize100'
|
|
1224
|
-
- name: sortBy
|
|
1746
|
+
- $ref: '#/components/parameters/startDate'
|
|
1747
|
+
- $ref: '#/components/parameters/endDate'
|
|
1748
|
+
- name: engagementContext
|
|
1225
1749
|
in: query
|
|
1226
1750
|
schema:
|
|
1227
1751
|
type: string
|
|
1228
|
-
enum: [
|
|
1229
|
-
|
|
1230
|
-
- $ref: '#/components/parameters/sortOrder'
|
|
1752
|
+
enum: [catalog, playlist]
|
|
1753
|
+
description: Filter to a single engagement context. Omit to return both.
|
|
1231
1754
|
responses:
|
|
1232
1755
|
'200':
|
|
1233
|
-
description:
|
|
1756
|
+
description: |
|
|
1757
|
+
JSONL stream. Each line is a `soundlink_engagement_daily` v1.0 row.
|
|
1758
|
+
Lines are sorted by `(report_date asc, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
1759
|
+
headers:
|
|
1760
|
+
Content-Disposition:
|
|
1761
|
+
schema:
|
|
1762
|
+
type: string
|
|
1763
|
+
description: |
|
|
1764
|
+
`attachment; filename="engagement_{soundlinkId}_{startDate}_{endDate}.jsonl"`
|
|
1765
|
+
example: 'attachment; filename="engagement_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
|
|
1766
|
+
X-Row-Count:
|
|
1767
|
+
schema:
|
|
1768
|
+
type: integer
|
|
1769
|
+
description: Total number of rows in the response. Useful for progress tracking when streaming.
|
|
1234
1770
|
content:
|
|
1235
|
-
application/
|
|
1771
|
+
application/x-ndjson:
|
|
1236
1772
|
schema:
|
|
1237
|
-
$ref: '#/components/schemas/
|
|
1238
|
-
example:
|
|
1239
|
-
|
|
1240
|
-
|
|
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
|
|
1251
|
-
pagination:
|
|
1252
|
-
page: 1
|
|
1253
|
-
pageSize: 10
|
|
1254
|
-
totalCount: 24
|
|
1255
|
-
totalPages: 3
|
|
1256
|
-
meta:
|
|
1257
|
-
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1773
|
+
$ref: '#/components/schemas/SoundlinkEngagementDailyRow'
|
|
1774
|
+
example: |
|
|
1775
|
+
{"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}
|
|
1776
|
+
{"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}
|
|
1258
1777
|
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1259
1778
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1260
1779
|
'403': { $ref: '#/components/responses/Forbidden' }
|
|
@@ -1472,18 +1991,6 @@ components:
|
|
|
1472
1991
|
Inclusive start date (`YYYY-MM-DD`) for soundlink overview and
|
|
1473
1992
|
timeseries. Defaults to the soundlink creation date when omitted.
|
|
1474
1993
|
|
|
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
1994
|
soundlinkEndDate:
|
|
1488
1995
|
name: endDate
|
|
1489
1996
|
in: query
|
|
@@ -1528,9 +2035,7 @@ components:
|
|
|
1528
2035
|
- invalid_api_key
|
|
1529
2036
|
- api_key_revoked
|
|
1530
2037
|
- api_key_expired
|
|
1531
|
-
- invalid_token
|
|
1532
2038
|
- insufficient_scope
|
|
1533
|
-
- access_denied
|
|
1534
2039
|
- not_found
|
|
1535
2040
|
- campaign_not_found
|
|
1536
2041
|
- invalid_query_parameter
|
|
@@ -2352,6 +2857,27 @@ components:
|
|
|
2352
2857
|
meta:
|
|
2353
2858
|
$ref: '#/components/schemas/Meta'
|
|
2354
2859
|
|
|
2860
|
+
MetricsEngagementResponse:
|
|
2861
|
+
type: object
|
|
2862
|
+
required: [data, meta]
|
|
2863
|
+
properties:
|
|
2864
|
+
data:
|
|
2865
|
+
type: object
|
|
2866
|
+
required: [schemaVersion, items, pagination]
|
|
2867
|
+
properties:
|
|
2868
|
+
schemaVersion:
|
|
2869
|
+
type: string
|
|
2870
|
+
description: Version of the `campaign_engagement_daily` row schema. Pin your ingest pipeline to this.
|
|
2871
|
+
example: '1.0'
|
|
2872
|
+
items:
|
|
2873
|
+
type: array
|
|
2874
|
+
items:
|
|
2875
|
+
$ref: '#/components/schemas/EngagementRow'
|
|
2876
|
+
pagination:
|
|
2877
|
+
$ref: '#/components/schemas/Pagination'
|
|
2878
|
+
meta:
|
|
2879
|
+
$ref: '#/components/schemas/Meta'
|
|
2880
|
+
|
|
2355
2881
|
# --- Engagement ---
|
|
2356
2882
|
|
|
2357
2883
|
EngagementRow:
|
|
@@ -2569,17 +3095,50 @@ components:
|
|
|
2569
3095
|
meta:
|
|
2570
3096
|
$ref: '#/components/schemas/Meta'
|
|
2571
3097
|
|
|
3098
|
+
CreateSoundlinkRequest:
|
|
3099
|
+
type: object
|
|
3100
|
+
required: [name, spotifyUrl]
|
|
3101
|
+
properties:
|
|
3102
|
+
name:
|
|
3103
|
+
type: string
|
|
3104
|
+
minLength: 1
|
|
3105
|
+
description: Human-readable soundlink name.
|
|
3106
|
+
spotifyUrl:
|
|
3107
|
+
type: string
|
|
3108
|
+
format: uri
|
|
3109
|
+
description: HTTPS Spotify track or playlist URL.
|
|
3110
|
+
example: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
|
|
3111
|
+
autoFollow:
|
|
3112
|
+
type: boolean
|
|
3113
|
+
default: false
|
|
3114
|
+
artistIdFollow:
|
|
3115
|
+
type: string
|
|
3116
|
+
metaPixelId:
|
|
3117
|
+
type: string
|
|
3118
|
+
metaConversionAccessToken:
|
|
3119
|
+
type: string
|
|
3120
|
+
writeOnly: true
|
|
3121
|
+
description: |
|
|
3122
|
+
Meta Conversions API access token. Write-only: accepted on create,
|
|
3123
|
+
never returned on GET. Must be sent together with `metaPixelId`.
|
|
3124
|
+
|
|
2572
3125
|
SoundlinkDetail:
|
|
2573
3126
|
allOf:
|
|
2574
3127
|
- $ref: '#/components/schemas/SoundlinkSummary'
|
|
2575
3128
|
- type: object
|
|
2576
|
-
required: [autoFollow, metaPixelId, tiktokPixelId]
|
|
3129
|
+
required: [autoFollow, artistIdFollow, metaPixelId, tiktokPixelId]
|
|
2577
3130
|
properties:
|
|
2578
3131
|
autoFollow:
|
|
2579
3132
|
type: boolean
|
|
2580
3133
|
description: |
|
|
2581
3134
|
Whether auto-follow is configured for this soundlink. Whether
|
|
2582
3135
|
it takes effect also depends on the organization's plan.
|
|
3136
|
+
artistIdFollow:
|
|
3137
|
+
type: string
|
|
3138
|
+
nullable: true
|
|
3139
|
+
description: |
|
|
3140
|
+
Spotify artist ID configured for auto-follow on track links.
|
|
3141
|
+
Unused for playlists. `null` if not set.
|
|
2583
3142
|
metaPixelId:
|
|
2584
3143
|
type: string
|
|
2585
3144
|
nullable: true
|
|
@@ -2600,12 +3159,129 @@ components:
|
|
|
2600
3159
|
|
|
2601
3160
|
SoundlinkMetricsOverview:
|
|
2602
3161
|
type: object
|
|
2603
|
-
description:
|
|
3162
|
+
description: |
|
|
3163
|
+
Soundlink-level totals for the requested date range. Additive fields
|
|
3164
|
+
are sums of `api_smart_link_country_daily` country-day rows.
|
|
2604
3165
|
required: [views, streams, listeners, followers, streams_per_listener]
|
|
2605
3166
|
properties:
|
|
2606
3167
|
views:
|
|
2607
3168
|
type: integer
|
|
2608
|
-
description: Soundlink landing page views in the period.
|
|
3169
|
+
description: Soundlink landing page views in the period (sum of country-day rows).
|
|
3170
|
+
link_clicks:
|
|
3171
|
+
type: integer
|
|
3172
|
+
nullable: true
|
|
3173
|
+
description: |
|
|
3174
|
+
Clicks on "Continue with Spotify" on the landing page — outbound
|
|
3175
|
+
clicks to Spotify. Null if not tracked for this soundlink type.
|
|
3176
|
+
streams:
|
|
3177
|
+
type: integer
|
|
3178
|
+
description: Attributed Spotify streams (sum of country-day rows).
|
|
3179
|
+
listeners:
|
|
3180
|
+
type: integer
|
|
3181
|
+
description: |
|
|
3182
|
+
Sum of country-day `new_listeners` from the mart (first-play
|
|
3183
|
+
attributed listeners). Not period-unique across days/countries,
|
|
3184
|
+
and not equal to summing breakdown `listeners` (new + returning).
|
|
3185
|
+
followers:
|
|
3186
|
+
type: integer
|
|
3187
|
+
description: Attributed Spotify artist follower gains in the period.
|
|
3188
|
+
streams_per_listener:
|
|
3189
|
+
type: number
|
|
3190
|
+
description: streams / listeners. Zero if listeners is zero.
|
|
3191
|
+
ctr_lp:
|
|
3192
|
+
type: number
|
|
3193
|
+
nullable: true
|
|
3194
|
+
description: |
|
|
3195
|
+
Landing page click-through rate (link_clicks / views). Computed
|
|
3196
|
+
against landing page views, not ad impressions — do not combine
|
|
3197
|
+
with `ctr_linkclick` from campaign metrics. Null if views is zero
|
|
3198
|
+
or link_clicks is null.
|
|
3199
|
+
|
|
3200
|
+
SoundlinkMetricsOverviewResponse:
|
|
3201
|
+
type: object
|
|
3202
|
+
required: [data, meta]
|
|
3203
|
+
properties:
|
|
3204
|
+
data:
|
|
3205
|
+
$ref: '#/components/schemas/SoundlinkMetricsOverview'
|
|
3206
|
+
meta:
|
|
3207
|
+
$ref: '#/components/schemas/Meta'
|
|
3208
|
+
|
|
3209
|
+
SoundlinkDailyRow:
|
|
3210
|
+
type: object
|
|
3211
|
+
description: |
|
|
3212
|
+
One row of the `soundlink_daily` v1.0 schema.
|
|
3213
|
+
Primary key: `(provider, account_id, report_date, soundlink_id)`.
|
|
3214
|
+
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
3215
|
+
Values for a given `report_date` may be revised for up to 7 days after
|
|
3216
|
+
the date closes due to delayed Spotify playback events.
|
|
3217
|
+
Rows are aggregated across countries (no `country_code` in v1.0) and
|
|
3218
|
+
contain no financial fields.
|
|
3219
|
+
required:
|
|
3220
|
+
- provider
|
|
3221
|
+
- account_id
|
|
3222
|
+
- schema_version
|
|
3223
|
+
- report_date
|
|
3224
|
+
- report_date_timezone
|
|
3225
|
+
- exported_at
|
|
3226
|
+
- soundlink_id
|
|
3227
|
+
- soundlink_name
|
|
3228
|
+
- soundlink_target_type
|
|
3229
|
+
- views
|
|
3230
|
+
- streams
|
|
3231
|
+
- listeners
|
|
3232
|
+
- followers
|
|
3233
|
+
- streams_per_listener
|
|
3234
|
+
properties:
|
|
3235
|
+
provider:
|
|
3236
|
+
type: string
|
|
3237
|
+
enum: [soundlink]
|
|
3238
|
+
description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
|
|
3239
|
+
account_id:
|
|
3240
|
+
type: string
|
|
3241
|
+
description: Soundlink organization ID (UUID).
|
|
3242
|
+
schema_version:
|
|
3243
|
+
type: string
|
|
3244
|
+
description: Schema version. Pin your ingest pipeline to this value.
|
|
3245
|
+
example: '1.0'
|
|
3246
|
+
report_date:
|
|
3247
|
+
type: string
|
|
3248
|
+
format: date
|
|
3249
|
+
description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
|
|
3250
|
+
report_date_timezone:
|
|
3251
|
+
type: string
|
|
3252
|
+
enum: [UTC]
|
|
3253
|
+
description: Always `UTC`.
|
|
3254
|
+
exported_at:
|
|
3255
|
+
type: string
|
|
3256
|
+
format: date-time
|
|
3257
|
+
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
3258
|
+
soundlink_id:
|
|
3259
|
+
type: string
|
|
3260
|
+
description: Unique ID of this soundlink.
|
|
3261
|
+
example: V1StGXR8_Z5jdHi6B-myT
|
|
3262
|
+
soundlink_name:
|
|
3263
|
+
type: string
|
|
3264
|
+
description: Human-readable soundlink name.
|
|
3265
|
+
soundlink_target_type:
|
|
3266
|
+
type: string
|
|
3267
|
+
nullable: true
|
|
3268
|
+
enum: [track, playlist]
|
|
3269
|
+
description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
|
|
3270
|
+
soundlink_target_isrc:
|
|
3271
|
+
type: string
|
|
3272
|
+
nullable: true
|
|
3273
|
+
description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3274
|
+
soundlink_target_spotify_track_id:
|
|
3275
|
+
type: string
|
|
3276
|
+
nullable: true
|
|
3277
|
+
description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3278
|
+
soundlink_target_playlist_id:
|
|
3279
|
+
type: string
|
|
3280
|
+
nullable: true
|
|
3281
|
+
description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
|
|
3282
|
+
views:
|
|
3283
|
+
type: integer
|
|
3284
|
+
description: Soundlink landing page views on this day.
|
|
2609
3285
|
link_clicks:
|
|
2610
3286
|
type: integer
|
|
2611
3287
|
nullable: true
|
|
@@ -2614,60 +3290,78 @@ components:
|
|
|
2614
3290
|
clicks to Spotify. Null if not tracked for this soundlink type.
|
|
2615
3291
|
streams:
|
|
2616
3292
|
type: integer
|
|
2617
|
-
description:
|
|
3293
|
+
description: |
|
|
3294
|
+
Spotify streams attributed to this soundlink on this day:
|
|
3295
|
+
`new_listener_streams + returning_listener_streams`. Observed
|
|
3296
|
+
Spotify-side events, not modelled estimates. Safe to sum within a
|
|
3297
|
+
day; summing across days counts repeat listens.
|
|
2618
3298
|
listeners:
|
|
2619
3299
|
type: integer
|
|
2620
|
-
description:
|
|
3300
|
+
description: |
|
|
3301
|
+
Unique Spotify listeners attributed to this soundlink on this day:
|
|
3302
|
+
`new_listeners + returning_listeners`. **Do not sum across days** —
|
|
3303
|
+
the same listener can appear on multiple `report_date` rows.
|
|
2621
3304
|
new_listeners:
|
|
2622
3305
|
type: integer
|
|
2623
3306
|
nullable: true
|
|
2624
|
-
description: Unique listeners whose first play via this soundlink occurred
|
|
3307
|
+
description: Unique listeners whose first play via this soundlink occurred on `report_date`.
|
|
2625
3308
|
returning_listeners:
|
|
2626
3309
|
type: integer
|
|
2627
3310
|
nullable: true
|
|
2628
|
-
description: Unique listeners who played
|
|
3311
|
+
description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
|
|
2629
3312
|
new_listener_streams:
|
|
2630
3313
|
type: integer
|
|
2631
3314
|
nullable: true
|
|
2632
|
-
description: Stream count from new listeners
|
|
3315
|
+
description: Stream count from new listeners on `report_date`.
|
|
2633
3316
|
returning_listener_streams:
|
|
2634
3317
|
type: integer
|
|
2635
3318
|
nullable: true
|
|
2636
|
-
description: Stream count from returning listeners
|
|
3319
|
+
description: Stream count from returning listeners on `report_date`.
|
|
2637
3320
|
followers:
|
|
2638
3321
|
type: integer
|
|
2639
|
-
description:
|
|
3322
|
+
description: Spotify artist follower gains attributed to this soundlink on this day.
|
|
2640
3323
|
streams_per_listener:
|
|
2641
3324
|
type: number
|
|
2642
|
-
description: streams / listeners. Zero if listeners is zero.
|
|
3325
|
+
description: streams / listeners for this row. Zero if listeners is zero.
|
|
2643
3326
|
ctr_lp:
|
|
2644
3327
|
type: number
|
|
2645
3328
|
nullable: true
|
|
2646
3329
|
description: |
|
|
2647
3330
|
Landing page click-through rate (link_clicks / views). Computed
|
|
2648
3331
|
against landing page views, not ad impressions — do not combine
|
|
2649
|
-
with `ctr_linkclick` from
|
|
2650
|
-
or link_clicks is null.
|
|
3332
|
+
with `ctr_linkclick` from `campaign_country_daily`. Null if views
|
|
3333
|
+
is zero or link_clicks is null.
|
|
2651
3334
|
|
|
2652
|
-
|
|
3335
|
+
SoundlinkTimeseriesResponse:
|
|
2653
3336
|
type: object
|
|
2654
3337
|
required: [data, meta]
|
|
2655
3338
|
properties:
|
|
2656
3339
|
data:
|
|
2657
|
-
|
|
3340
|
+
type: object
|
|
3341
|
+
required: [schemaVersion, items, pagination]
|
|
3342
|
+
properties:
|
|
3343
|
+
schemaVersion:
|
|
3344
|
+
type: string
|
|
3345
|
+
description: Version of the `soundlink_daily` row schema. Pin your ingest pipeline to this.
|
|
3346
|
+
example: '1.0'
|
|
3347
|
+
items:
|
|
3348
|
+
type: array
|
|
3349
|
+
items:
|
|
3350
|
+
$ref: '#/components/schemas/SoundlinkDailyRow'
|
|
3351
|
+
pagination:
|
|
3352
|
+
$ref: '#/components/schemas/Pagination'
|
|
2658
3353
|
meta:
|
|
2659
3354
|
$ref: '#/components/schemas/Meta'
|
|
2660
3355
|
|
|
2661
|
-
|
|
3356
|
+
SoundlinkCountryDailyRow:
|
|
2662
3357
|
type: object
|
|
2663
3358
|
description: |
|
|
2664
|
-
One row of the `
|
|
2665
|
-
Primary key: `(provider, account_id, report_date, soundlink_id)`.
|
|
3359
|
+
One row of the `soundlink_country_daily` v1.0 schema.
|
|
3360
|
+
Primary key: `(provider, account_id, report_date, soundlink_id, country_code)`.
|
|
2666
3361
|
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
2667
3362
|
Values for a given `report_date` may be revised for up to 7 days after
|
|
2668
3363
|
the date closes due to delayed Spotify playback events.
|
|
2669
|
-
Rows
|
|
2670
|
-
contain no financial fields.
|
|
3364
|
+
Rows contain no financial fields.
|
|
2671
3365
|
required:
|
|
2672
3366
|
- provider
|
|
2673
3367
|
- account_id
|
|
@@ -2678,6 +3372,7 @@ components:
|
|
|
2678
3372
|
- soundlink_id
|
|
2679
3373
|
- soundlink_name
|
|
2680
3374
|
- soundlink_target_type
|
|
3375
|
+
- country_code
|
|
2681
3376
|
- views
|
|
2682
3377
|
- streams
|
|
2683
3378
|
- listeners
|
|
@@ -2731,9 +3426,12 @@ components:
|
|
|
2731
3426
|
type: string
|
|
2732
3427
|
nullable: true
|
|
2733
3428
|
description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
|
|
3429
|
+
country_code:
|
|
3430
|
+
type: string
|
|
3431
|
+
description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
|
|
2734
3432
|
views:
|
|
2735
3433
|
type: integer
|
|
2736
|
-
description: Soundlink landing page views on this day.
|
|
3434
|
+
description: Soundlink landing page views in this country on this day.
|
|
2737
3435
|
link_clicks:
|
|
2738
3436
|
type: integer
|
|
2739
3437
|
nullable: true
|
|
@@ -2743,35 +3441,36 @@ components:
|
|
|
2743
3441
|
streams:
|
|
2744
3442
|
type: integer
|
|
2745
3443
|
description: |
|
|
2746
|
-
Spotify streams attributed to this soundlink on this
|
|
2747
|
-
`new_listener_streams + returning_listener_streams`. Observed
|
|
3444
|
+
Spotify streams attributed to this soundlink in this country on this
|
|
3445
|
+
day: `new_listener_streams + returning_listener_streams`. Observed
|
|
2748
3446
|
Spotify-side events, not modelled estimates. Safe to sum within a
|
|
2749
3447
|
day; summing across days counts repeat listens.
|
|
2750
3448
|
listeners:
|
|
2751
3449
|
type: integer
|
|
2752
3450
|
description: |
|
|
2753
|
-
Unique Spotify listeners attributed to this soundlink
|
|
2754
|
-
`new_listeners + returning_listeners`.
|
|
2755
|
-
the same listener can appear on
|
|
3451
|
+
Unique Spotify listeners attributed to this soundlink in this
|
|
3452
|
+
country on this day: `new_listeners + returning_listeners`.
|
|
3453
|
+
**Do not sum across days** — the same listener can appear on
|
|
3454
|
+
multiple `report_date` rows.
|
|
2756
3455
|
new_listeners:
|
|
2757
3456
|
type: integer
|
|
2758
3457
|
nullable: true
|
|
2759
|
-
description: Unique listeners whose first play via this soundlink occurred on `report_date
|
|
3458
|
+
description: Unique listeners whose first play via this soundlink occurred on `report_date` in this country.
|
|
2760
3459
|
returning_listeners:
|
|
2761
3460
|
type: integer
|
|
2762
3461
|
nullable: true
|
|
2763
|
-
description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
|
|
3462
|
+
description: Unique listeners who played on `report_date` in this country but whose first play was on an earlier date.
|
|
2764
3463
|
new_listener_streams:
|
|
2765
3464
|
type: integer
|
|
2766
3465
|
nullable: true
|
|
2767
|
-
description: Stream count from new listeners on `report_date
|
|
3466
|
+
description: Stream count from new listeners on `report_date` in this country.
|
|
2768
3467
|
returning_listener_streams:
|
|
2769
3468
|
type: integer
|
|
2770
3469
|
nullable: true
|
|
2771
|
-
description: Stream count from returning listeners on `report_date
|
|
3470
|
+
description: Stream count from returning listeners on `report_date` in this country.
|
|
2772
3471
|
followers:
|
|
2773
3472
|
type: integer
|
|
2774
|
-
description: Spotify artist follower gains attributed to this soundlink on this day.
|
|
3473
|
+
description: Spotify artist follower gains attributed to this soundlink in this country on this day.
|
|
2775
3474
|
streams_per_listener:
|
|
2776
3475
|
type: number
|
|
2777
3476
|
description: streams / listeners for this row. Zero if listeners is zero.
|
|
@@ -2784,7 +3483,7 @@ components:
|
|
|
2784
3483
|
with `ctr_linkclick` from `campaign_country_daily`. Null if views
|
|
2785
3484
|
is zero or link_clicks is null.
|
|
2786
3485
|
|
|
2787
|
-
|
|
3486
|
+
SoundlinkBreakdownResponse:
|
|
2788
3487
|
type: object
|
|
2789
3488
|
required: [data, meta]
|
|
2790
3489
|
properties:
|
|
@@ -2794,60 +3493,180 @@ components:
|
|
|
2794
3493
|
properties:
|
|
2795
3494
|
schemaVersion:
|
|
2796
3495
|
type: string
|
|
2797
|
-
description: Version of the `
|
|
3496
|
+
description: Version of the `soundlink_country_daily` row schema. Pin your ingest pipeline to this.
|
|
2798
3497
|
example: '1.0'
|
|
2799
3498
|
items:
|
|
2800
3499
|
type: array
|
|
2801
3500
|
items:
|
|
2802
|
-
$ref: '#/components/schemas/
|
|
3501
|
+
$ref: '#/components/schemas/SoundlinkCountryDailyRow'
|
|
2803
3502
|
pagination:
|
|
2804
3503
|
$ref: '#/components/schemas/Pagination'
|
|
2805
3504
|
meta:
|
|
2806
3505
|
$ref: '#/components/schemas/Meta'
|
|
2807
3506
|
|
|
2808
|
-
SoundlinkEngagementItem:
|
|
2809
|
-
type: object
|
|
2810
|
-
description: |
|
|
2811
|
-
One track aggregated over the requested date range (period totals,
|
|
2812
|
-
not daily rows).
|
|
2813
|
-
required: [trackId, trackName, totalStreams, totalListeners, streamsPerListener]
|
|
2814
|
-
properties:
|
|
2815
|
-
trackId:
|
|
2816
|
-
type: string
|
|
2817
|
-
description: Spotify track ID of the engaged track.
|
|
2818
|
-
example: 4cOdK2wGLETKBW3PvgPWqT
|
|
2819
|
-
trackName:
|
|
2820
|
-
type: string
|
|
2821
|
-
description: Display name of the engaged track.
|
|
2822
|
-
totalStreams:
|
|
2823
|
-
type: integer
|
|
2824
|
-
minimum: 0
|
|
2825
|
-
description: Total streams of this track in the period.
|
|
2826
|
-
totalListeners:
|
|
2827
|
-
type: integer
|
|
2828
|
-
minimum: 0
|
|
2829
|
-
description: Unique listeners of this track in the period.
|
|
2830
|
-
streamsPerListener:
|
|
2831
|
-
type: number
|
|
2832
|
-
description: totalStreams / totalListeners. Zero if totalListeners is zero.
|
|
2833
|
-
|
|
2834
3507
|
SoundlinkEngagementResponse:
|
|
2835
3508
|
type: object
|
|
2836
3509
|
required: [data, meta]
|
|
2837
3510
|
properties:
|
|
2838
3511
|
data:
|
|
2839
3512
|
type: object
|
|
2840
|
-
required: [items, pagination]
|
|
3513
|
+
required: [schemaVersion, items, pagination]
|
|
2841
3514
|
properties:
|
|
3515
|
+
schemaVersion:
|
|
3516
|
+
type: string
|
|
3517
|
+
description: Version of the `soundlink_engagement_daily` row schema. Pin your ingest pipeline to this.
|
|
3518
|
+
example: '1.0'
|
|
2842
3519
|
items:
|
|
2843
3520
|
type: array
|
|
2844
3521
|
items:
|
|
2845
|
-
$ref: '#/components/schemas/
|
|
3522
|
+
$ref: '#/components/schemas/SoundlinkEngagementDailyRow'
|
|
2846
3523
|
pagination:
|
|
2847
3524
|
$ref: '#/components/schemas/Pagination'
|
|
2848
3525
|
meta:
|
|
2849
3526
|
$ref: '#/components/schemas/Meta'
|
|
2850
3527
|
|
|
3528
|
+
SoundlinkEngagementDailyRow:
|
|
3529
|
+
type: object
|
|
3530
|
+
description: |
|
|
3531
|
+
One row of the `soundlink_engagement_daily` v1.0 schema.
|
|
3532
|
+
Primary key: `(provider, account_id, report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
3533
|
+
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
3534
|
+
Values for a given `report_date` may be revised for up to 7 days after
|
|
3535
|
+
the date closes due to delayed Spotify playback events.
|
|
3536
|
+
No `status` field: soundlinks do not store per-day lifecycle history.
|
|
3537
|
+
No financial fields.
|
|
3538
|
+
required:
|
|
3539
|
+
- provider
|
|
3540
|
+
- account_id
|
|
3541
|
+
- schema_version
|
|
3542
|
+
- report_date
|
|
3543
|
+
- report_date_timezone
|
|
3544
|
+
- exported_at
|
|
3545
|
+
- soundlink_id
|
|
3546
|
+
- soundlink_name
|
|
3547
|
+
- soundlink_target_type
|
|
3548
|
+
- engagement_context
|
|
3549
|
+
- country_code
|
|
3550
|
+
- engaged_spotify_track_id
|
|
3551
|
+
- engaged_track_name
|
|
3552
|
+
- new_listeners
|
|
3553
|
+
- returning_listeners
|
|
3554
|
+
- listeners
|
|
3555
|
+
- new_listener_streams
|
|
3556
|
+
- returning_listener_streams
|
|
3557
|
+
- streams
|
|
3558
|
+
- spl
|
|
3559
|
+
properties:
|
|
3560
|
+
provider:
|
|
3561
|
+
type: string
|
|
3562
|
+
enum: [soundlink]
|
|
3563
|
+
description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
|
|
3564
|
+
account_id:
|
|
3565
|
+
type: string
|
|
3566
|
+
description: Soundlink organization ID (UUID).
|
|
3567
|
+
schema_version:
|
|
3568
|
+
type: string
|
|
3569
|
+
description: Schema version string. Pin your ingest pipeline to this value.
|
|
3570
|
+
example: '1.0'
|
|
3571
|
+
report_date:
|
|
3572
|
+
type: string
|
|
3573
|
+
format: date
|
|
3574
|
+
description: UTC calendar date the metrics belong to (`YYYY-MM-DD`). Rows can change for up to 7 days after close.
|
|
3575
|
+
report_date_timezone:
|
|
3576
|
+
type: string
|
|
3577
|
+
enum: [UTC]
|
|
3578
|
+
description: Always `UTC`.
|
|
3579
|
+
exported_at:
|
|
3580
|
+
type: string
|
|
3581
|
+
format: date-time
|
|
3582
|
+
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
3583
|
+
soundlink_id:
|
|
3584
|
+
type: string
|
|
3585
|
+
description: Unique ID of this soundlink.
|
|
3586
|
+
example: V1StGXR8_Z5jdHi6B-myT
|
|
3587
|
+
soundlink_name:
|
|
3588
|
+
type: string
|
|
3589
|
+
description: Human-readable soundlink name.
|
|
3590
|
+
soundlink_target_type:
|
|
3591
|
+
type: string
|
|
3592
|
+
nullable: true
|
|
3593
|
+
enum: [track, playlist]
|
|
3594
|
+
description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
|
|
3595
|
+
soundlink_target_isrc:
|
|
3596
|
+
type: string
|
|
3597
|
+
nullable: true
|
|
3598
|
+
description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3599
|
+
soundlink_target_spotify_track_id:
|
|
3600
|
+
type: string
|
|
3601
|
+
nullable: true
|
|
3602
|
+
description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3603
|
+
soundlink_target_playlist_id:
|
|
3604
|
+
type: string
|
|
3605
|
+
nullable: true
|
|
3606
|
+
description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
|
|
3607
|
+
engagement_context:
|
|
3608
|
+
type: string
|
|
3609
|
+
enum: [catalog, playlist]
|
|
3610
|
+
description: |
|
|
3611
|
+
Which section this row belongs to.
|
|
3612
|
+
`catalog`: plays of the promoted track and same-artist catalog tracks (track soundlinks).
|
|
3613
|
+
`playlist`: per-track performance inside the promoted playlist (playlist soundlinks).
|
|
3614
|
+
country_code:
|
|
3615
|
+
type: string
|
|
3616
|
+
description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
|
|
3617
|
+
example: US
|
|
3618
|
+
engaged_track_isrc:
|
|
3619
|
+
type: string
|
|
3620
|
+
nullable: true
|
|
3621
|
+
description: |
|
|
3622
|
+
ISRC of the track that received listens. May differ from `soundlink_target_isrc`
|
|
3623
|
+
for catalog spillover rows. `null` if ISRC could not be resolved.
|
|
3624
|
+
engaged_spotify_track_id:
|
|
3625
|
+
type: string
|
|
3626
|
+
description: Spotify track ID of the engaged track. Part of the primary key.
|
|
3627
|
+
example: 4cOdK2wGLETKBW3PvgPWqT
|
|
3628
|
+
engaged_track_name:
|
|
3629
|
+
type: string
|
|
3630
|
+
description: Display name of the engaged track.
|
|
3631
|
+
playlist_position:
|
|
3632
|
+
type: integer
|
|
3633
|
+
nullable: true
|
|
3634
|
+
minimum: 1
|
|
3635
|
+
description: |
|
|
3636
|
+
1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
|
|
3637
|
+
Populated only when `engagement_context = playlist`. Treat `null` as unavailable, not an error.
|
|
3638
|
+
new_listeners:
|
|
3639
|
+
type: integer
|
|
3640
|
+
minimum: 0
|
|
3641
|
+
description: Unique listeners whose first play of this track via this soundlink occurred on `report_date`.
|
|
3642
|
+
returning_listeners:
|
|
3643
|
+
type: integer
|
|
3644
|
+
minimum: 0
|
|
3645
|
+
description: Unique listeners who played this track on `report_date` but whose first play was on an earlier date.
|
|
3646
|
+
listeners:
|
|
3647
|
+
type: integer
|
|
3648
|
+
minimum: 0
|
|
3649
|
+
description: |
|
|
3650
|
+
Total unique listeners on `report_date`: `new_listeners + returning_listeners`.
|
|
3651
|
+
**Do not sum across days** — the same listener can appear on multiple `report_date` rows.
|
|
3652
|
+
new_listener_streams:
|
|
3653
|
+
type: integer
|
|
3654
|
+
minimum: 0
|
|
3655
|
+
description: Stream count from new listeners on `report_date`.
|
|
3656
|
+
returning_listener_streams:
|
|
3657
|
+
type: integer
|
|
3658
|
+
minimum: 0
|
|
3659
|
+
description: Stream count from returning listeners on `report_date`.
|
|
3660
|
+
streams:
|
|
3661
|
+
type: integer
|
|
3662
|
+
minimum: 0
|
|
3663
|
+
description: |
|
|
3664
|
+
Total streams on `report_date`: `new_listener_streams + returning_listener_streams`.
|
|
3665
|
+
Safe to sum within a day; summing across days counts repeat listens.
|
|
3666
|
+
spl:
|
|
3667
|
+
type: number
|
|
3668
|
+
description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
|
|
3669
|
+
|
|
2851
3670
|
# --- Videos ---
|
|
2852
3671
|
|
|
2853
3672
|
VideoImportRequest:
|
|
@@ -3182,6 +4001,69 @@ components:
|
|
|
3182
4001
|
meta:
|
|
3183
4002
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
3184
4003
|
|
|
4004
|
+
CreateSoundlinkBadRequest:
|
|
4005
|
+
description: |
|
|
4006
|
+
Missing or malformed request body, or a missing/empty
|
|
4007
|
+
`Idempotency-Key` header.
|
|
4008
|
+
content:
|
|
4009
|
+
application/json:
|
|
4010
|
+
schema:
|
|
4011
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
4012
|
+
examples:
|
|
4013
|
+
missing_field:
|
|
4014
|
+
value:
|
|
4015
|
+
error:
|
|
4016
|
+
code: invalid_request
|
|
4017
|
+
message: 'Missing required field: name.'
|
|
4018
|
+
meta:
|
|
4019
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4020
|
+
missing_idempotency_key:
|
|
4021
|
+
value:
|
|
4022
|
+
error:
|
|
4023
|
+
code: invalid_request
|
|
4024
|
+
message: 'Idempotency-Key header is required and must not be empty.'
|
|
4025
|
+
meta:
|
|
4026
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4027
|
+
pixel_pair:
|
|
4028
|
+
value:
|
|
4029
|
+
error:
|
|
4030
|
+
code: invalid_request
|
|
4031
|
+
message: 'metaPixelId and metaConversionAccessToken must both be provided, or both omitted.'
|
|
4032
|
+
meta:
|
|
4033
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4034
|
+
|
|
4035
|
+
CreateSoundlinkForbidden:
|
|
4036
|
+
description: |
|
|
4037
|
+
Valid credentials but missing the `soundlinks:write` scope.
|
|
4038
|
+
content:
|
|
4039
|
+
application/json:
|
|
4040
|
+
schema:
|
|
4041
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
4042
|
+
examples:
|
|
4043
|
+
insufficient_scope:
|
|
4044
|
+
value:
|
|
4045
|
+
error:
|
|
4046
|
+
code: insufficient_scope
|
|
4047
|
+
message: 'This key does not have the soundlinks:write scope.'
|
|
4048
|
+
meta:
|
|
4049
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4050
|
+
|
|
4051
|
+
CreateSoundlinkUnprocessable:
|
|
4052
|
+
description: Request body is well-formed but the Spotify URL is invalid.
|
|
4053
|
+
content:
|
|
4054
|
+
application/json:
|
|
4055
|
+
schema:
|
|
4056
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
4057
|
+
examples:
|
|
4058
|
+
invalid_spotify_url:
|
|
4059
|
+
summary: Malformed URL, unsupported type, or Spotify resource does not exist
|
|
4060
|
+
value:
|
|
4061
|
+
error:
|
|
4062
|
+
code: invalid_spotify_url
|
|
4063
|
+
message: 'Spotify track not found.'
|
|
4064
|
+
meta:
|
|
4065
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4066
|
+
|
|
3185
4067
|
IdempotencyKeyConflict:
|
|
3186
4068
|
description: |
|
|
3187
4069
|
The `Idempotency-Key` was reused with a materially different request
|