soundlink 2.4.0 → 2.5.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.
@@ -37,9 +37,13 @@ info:
37
37
  | `GET /v1/ping` | any granted Public API scope | API key (Bearer) or OAuth Bearer |
38
38
  | Campaign reads (`GET /v1/strategies`, `GET /v1/campaigns`, campaign detail, tiers) | `campaigns:read` | API key (Bearer) or OAuth Bearer |
39
39
  | Metrics reads (overview, breakdown, exports) | `metrics:read` | API key (Bearer) or OAuth Bearer |
40
+ | Campaign listening insights + campaign cohort retention (**Label / Enterprise / committed / self-serve**) | `metrics:read` | API key (Bearer) or OAuth Bearer |
40
41
  | Campaign writes (create, stop, budget, tier updates) | `campaigns:write` | API key (Bearer) or OAuth Bearer |
42
+ | Pixel reads (`GET /v1/pixels`) | `pixels:read` | API key (Bearer) or OAuth Bearer |
43
+ | Pixel writes (save pixel, test events) | `pixels:write` | API key (Bearer) or OAuth Bearer |
41
44
  | Video import / import status | `videos:write` | API key (Bearer) or OAuth Bearer |
42
45
  | Soundlink reads (list, detail, metrics overview/breakdown/engagement, JSONL exports) | `soundlinks:read` | API key (Bearer) or OAuth Bearer |
46
+ | Soundlink listening insights + soundlink cohort retention (**Label / Enterprise / committed / self-serve**) | `soundlinks:read` | API key (Bearer) or OAuth Bearer |
43
47
  | Soundlink writes (create, archive, test events) | `soundlinks:write` | API key (Bearer) or OAuth Bearer |
44
48
  | Wallet read (`GET /v1/wallet`) | `wallet:read` | API key (Bearer) or OAuth Bearer |
45
49
 
@@ -67,6 +71,8 @@ tags:
67
71
  description: Connectivity and auth verification
68
72
  - name: Wallet
69
73
  description: Organization wallet balance
74
+ - name: Pixels
75
+ description: Organization ad pixels that receive a copy of Soundlink conversion events
70
76
  - name: Campaigns
71
77
  description: Campaign listing, detail, creation, and wallet management (budget, stop, tiers)
72
78
  - name: Metrics
@@ -156,6 +162,164 @@ paths:
156
162
  '429': { $ref: '#/components/responses/RateLimited' }
157
163
  '500': { $ref: '#/components/responses/InternalError' }
158
164
 
165
+ /v1/pixels:
166
+ get:
167
+ operationId: listPixels
168
+ summary: List the organization's pixels
169
+ description: |
170
+ Returns the Meta pixels configured for the organization. Access tokens
171
+ are never returned. Today each entry has `platform: meta`.
172
+
173
+ Requires `pixels:read`. Organizations without custom pixels enabled
174
+ get `403 custom_pixel_not_enabled`.
175
+ tags: [Pixels]
176
+ x-required-scope: pixels:read
177
+ security:
178
+ - apiKeyBearerAuth: []
179
+ - oauthBearer: []
180
+
181
+ responses:
182
+ '200':
183
+ description: Pixels for the organization
184
+ content:
185
+ application/json:
186
+ schema:
187
+ $ref: '#/components/schemas/PixelListResponse'
188
+ example:
189
+ data:
190
+ pixels:
191
+ - id: '1234567890123456'
192
+ platform: meta
193
+ meta:
194
+ requestId: 550e8400-e29b-41d4-a716-446655440000
195
+ '401': { $ref: '#/components/responses/Unauthorized' }
196
+ '403': { $ref: '#/components/responses/PixelForbidden' }
197
+ '429': { $ref: '#/components/responses/RateLimited' }
198
+ '500': { $ref: '#/components/responses/InternalError' }
199
+
200
+ /v1/pixels/{pixelId}:
201
+ put:
202
+ operationId: updatePixel
203
+ summary: Save an organization pixel
204
+ description: |
205
+ Saves the Conversions API access token for `pixelId`. The same call
206
+ creates the pixel or rotates its token, and both return `200`:
207
+
208
+ - No Meta pixel yet: the pixel is saved.
209
+ - `pixelId` matches a Meta pixel the organization already has: its
210
+ access token is replaced.
211
+ - A different Meta pixel for the same organization: the new pixel is
212
+ saved alongside existing ones.
213
+ - The pixel is configured by another organization: `409
214
+ meta_pixel_conflict`.
215
+ - The access token is already used with another pixel: `400
216
+ invalid_request`.
217
+ - `platform` other than `meta`: `400 invalid_request`.
218
+
219
+ The response never includes the access token. Use
220
+ `POST /v1/pixels/{pixelId}/test-events` to check the pixel and token.
221
+
222
+ Requires `pixels:write`. Organizations without custom pixels enabled
223
+ get `403 custom_pixel_not_enabled`. Does not require `Idempotency-Key`;
224
+ repeating the same request is safe.
225
+
226
+ **Auth:** Accepts API key or OAuth Bearer (`pixels:write`).
227
+ tags: [Pixels]
228
+ x-required-scope: pixels:write
229
+ security:
230
+ - apiKeyBearerAuth: []
231
+ - oauthBearer: []
232
+
233
+ parameters:
234
+ - name: pixelId
235
+ in: path
236
+ required: true
237
+ schema:
238
+ type: string
239
+ minLength: 1
240
+ description: Pixel id on the ad platform.
241
+ requestBody:
242
+ required: true
243
+ content:
244
+ application/json:
245
+ schema:
246
+ $ref: '#/components/schemas/UpdatePixelRequest'
247
+ example:
248
+ platform: meta
249
+ accessToken: 'EAAB...'
250
+ responses:
251
+ '200':
252
+ description: Pixel saved or token rotated
253
+ content:
254
+ application/json:
255
+ schema:
256
+ $ref: '#/components/schemas/UpdatePixelResponse'
257
+ example:
258
+ data:
259
+ id: '1234567890123456'
260
+ platform: meta
261
+ meta:
262
+ requestId: 550e8400-e29b-41d4-a716-446655440000
263
+ '400': { $ref: '#/components/responses/UpdatePixelBadRequest' }
264
+ '401': { $ref: '#/components/responses/Unauthorized' }
265
+ '403': { $ref: '#/components/responses/PixelForbidden' }
266
+ '409': { $ref: '#/components/responses/PixelConflict' }
267
+ '429': { $ref: '#/components/responses/RateLimited' }
268
+ '500': { $ref: '#/components/responses/InternalError' }
269
+
270
+ /v1/pixels/{pixelId}/test-events:
271
+ post:
272
+ operationId: sendPixelTestEvents
273
+ summary: Send a test conversion event to a pixel
274
+ description: |
275
+ Sends a live Meta Conversions API event named `Soundlink Stream` to
276
+ `pixelId` with its stored access token. This is not a sandbox event:
277
+ it appears in the pixel's Events Manager as a regular event. This
278
+ request has no body.
279
+
280
+ Returns `404 not_found` when the pixel is not configured for the
281
+ organization. Returns `400 invalid_request` when Meta rejects the
282
+ event because the pixel id or access token is wrong. Does not require
283
+ `Idempotency-Key`; each call sends a new event.
284
+
285
+ Requires `pixels:write`. Organizations without custom pixels enabled
286
+ get `403 custom_pixel_not_enabled`.
287
+
288
+ **Auth:** Accepts API key or OAuth Bearer (`pixels:write`).
289
+ tags: [Pixels]
290
+ x-required-scope: pixels:write
291
+ security:
292
+ - apiKeyBearerAuth: []
293
+ - oauthBearer: []
294
+
295
+ parameters:
296
+ - name: pixelId
297
+ in: path
298
+ required: true
299
+ schema:
300
+ type: string
301
+ minLength: 1
302
+ description: Pixel id on the ad platform.
303
+ responses:
304
+ '200':
305
+ description: Test event sent
306
+ content:
307
+ application/json:
308
+ schema:
309
+ $ref: '#/components/schemas/PixelTestEventResponse'
310
+ example:
311
+ data:
312
+ status: sent
313
+ pixelId: '1234567890123456'
314
+ meta:
315
+ requestId: 550e8400-e29b-41d4-a716-446655440000
316
+ '400': { $ref: '#/components/responses/PixelTestEventBadRequest' }
317
+ '401': { $ref: '#/components/responses/Unauthorized' }
318
+ '403': { $ref: '#/components/responses/PixelForbidden' }
319
+ '404': { $ref: '#/components/responses/NotFound' }
320
+ '429': { $ref: '#/components/responses/RateLimited' }
321
+ '500': { $ref: '#/components/responses/InternalError' }
322
+
159
323
  /v1/strategies:
160
324
  get:
161
325
  operationId: listStrategies
@@ -654,8 +818,9 @@ paths:
654
818
  summary: Get campaign tier allocation
655
819
  description: |
656
820
  Returns the current geographic tier allocation for a wallet campaign:
657
- which tiers are enabled, their budget share, and when tiers were last
658
- updated (`lastUpdate`). Use this before `PATCH` to build a valid request.
821
+ which tiers are enabled, their budget share, learning status
822
+ (`learningStatus`), and when tiers were last updated (`lastUpdate`).
823
+ Use this before `PATCH` to build a valid request.
659
824
 
660
825
  **Wallet campaigns only** (`generation: 3`).
661
826
 
@@ -682,10 +847,12 @@ paths:
682
847
  tierName: US
683
848
  isEnabled: true
684
849
  allocationPercent: 60
850
+ learningStatus: LEARNING
685
851
  - tierId: 2
686
852
  tierName: UK
687
853
  isEnabled: false
688
854
  allocationPercent: 40
855
+ learningStatus: null
689
856
  meta:
690
857
  requestId: 550e8400-e29b-41d4-a716-446655440000
691
858
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -709,8 +876,13 @@ paths:
709
876
  - `newAllocationPercent` values must sum to **100**
710
877
  - At least one tier must have `isEnabled: true`
711
878
 
712
- **Cooldown:** after a successful update, further tier changes are
713
- blocked for **72 hours** (`409 tier_update_cooldown`).
879
+ **Learning:** within 72 hours of the latest tier or country targeting
880
+ update, a change is rejected with `409 learning_edit_ack_required`
881
+ when a tier that is active before the update has `learningStatus`
882
+ `LEARNING` or `FAIL`. Retry with `acknowledgeLearningWarning: true`
883
+ to continue. `SUCCESS`, `null`, and updates outside that window do
884
+ not require acknowledgement. A request that matches the current tier
885
+ state is accepted without writing.
714
886
 
715
887
  **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
716
888
  tags: [Campaigns]
@@ -734,6 +906,7 @@ paths:
734
906
  - targetingTierId: 2
735
907
  isEnabled: true
736
908
  newAllocationPercent: 30
909
+ acknowledgeLearningWarning: true
737
910
  responses:
738
911
  '200':
739
912
  description: Updated tier allocation
@@ -765,7 +938,83 @@ paths:
765
938
  '401': { $ref: '#/components/responses/Unauthorized' }
766
939
  '403': { $ref: '#/components/responses/Forbidden' }
767
940
  '404': { $ref: '#/components/responses/NotFound' }
768
- '409': { $ref: '#/components/responses/TierUpdateCooldown' }
941
+ '409': { $ref: '#/components/responses/LearningEditAckRequired' }
942
+ '429': { $ref: '#/components/responses/RateLimited' }
943
+ '500': { $ref: '#/components/responses/InternalError' }
944
+
945
+ /v1/campaigns/{campaignId}/activity:
946
+ get:
947
+ operationId: getCampaignActivity
948
+ summary: List campaign activity
949
+ description: |
950
+ Returns a page of creative adds, budget changes, tier updates, country
951
+ updates, playlist redirect heals, and auto-renew changes for one campaign.
952
+
953
+ Each item is an event type, a timestamp, and a short summary. The list
954
+ does not include campaign creation or pausing an old creative. Fee amounts,
955
+ Stripe ids, and internal file URIs are omitted.
956
+
957
+ `startDate` keeps events at or after that moment. A calendar date starts
958
+ at 00:00:00Z. Omit it to page through the full history. Any waiting rule,
959
+ such as 72 hours after a change, is applied by the caller.
960
+
961
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
962
+ tags: [Campaigns]
963
+ x-required-scope: campaigns:read
964
+ security:
965
+ - apiKeyBearerAuth: []
966
+ - oauthBearer: []
967
+ parameters:
968
+ - $ref: '#/components/parameters/campaignId'
969
+ - name: startDate
970
+ in: query
971
+ schema:
972
+ type: string
973
+ description: |
974
+ Return events at or after this moment. `YYYY-MM-DD` starts at
975
+ 00:00:00Z. An ISO-8601 timestamp uses that instant.
976
+ - name: page
977
+ in: query
978
+ schema:
979
+ type: integer
980
+ minimum: 1
981
+ default: 1
982
+ description: Page number (1-indexed).
983
+ - name: pageSize
984
+ in: query
985
+ schema:
986
+ type: integer
987
+ minimum: 1
988
+ maximum: 100
989
+ default: 20
990
+ description: Items per page (max 100).
991
+ responses:
992
+ '200':
993
+ description: Campaign activity page
994
+ content:
995
+ application/json:
996
+ schema:
997
+ $ref: '#/components/schemas/CampaignActivityResponse'
998
+ example:
999
+ data:
1000
+ items:
1001
+ - event_type: CAMPAIGN_AD_CREATIVES_ADDED
1002
+ timestamp: '2026-03-02T15:04:05.000Z'
1003
+ summary: Creatives added (2)
1004
+ - event_type: BUDGET_TOPUP
1005
+ timestamp: '2026-03-01T12:00:00.000Z'
1006
+ summary: Budget increased
1007
+ pagination:
1008
+ page: 1
1009
+ pageSize: 20
1010
+ totalCount: 2
1011
+ totalPages: 1
1012
+ meta:
1013
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1014
+ '400': { $ref: '#/components/responses/BadRequest' }
1015
+ '401': { $ref: '#/components/responses/Unauthorized' }
1016
+ '403': { $ref: '#/components/responses/Forbidden' }
1017
+ '404': { $ref: '#/components/responses/NotFound' }
769
1018
  '429': { $ref: '#/components/responses/RateLimited' }
770
1019
  '500': { $ref: '#/components/responses/InternalError' }
771
1020
 
@@ -774,8 +1023,9 @@ paths:
774
1023
  operationId: getCampaignMetricsOverview
775
1024
  summary: Campaign metrics overview
776
1025
  description: |
777
- Campaign-level totals for a date range: spend, conversions, listeners,
778
- streams, followers, and derived ratios. No per-day rows — use
1026
+ Campaign-level totals for a date range: spend, listeners (new),
1027
+ `total_listeners` (distinct), streams, followers, and derived ratios.
1028
+ `streams_per_listener` uses `total_listeners`. No per-day rows — use
779
1029
  `/metrics/breakdown` for those.
780
1030
 
781
1031
  Suitable for dashboards and quick syncs.
@@ -800,6 +1050,7 @@ paths:
800
1050
  example:
801
1051
  data:
802
1052
  listeners: 4821
1053
+ total_listeners: 5100
803
1054
  streams: 9340
804
1055
  followers: 312
805
1056
  impressions: 48210
@@ -811,7 +1062,7 @@ paths:
811
1062
  currency: USD
812
1063
  cpl: 0.028
813
1064
  cpf: 0.43
814
- streams_per_listener: 1.94
1065
+ streams_per_listener: 1.83
815
1066
  meta:
816
1067
  requestId: 550e8400-e29b-41d4-a716-446655440000
817
1068
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -827,8 +1078,11 @@ paths:
827
1078
  summary: Campaign creative metrics
828
1079
  description: |
829
1080
  Lifetime creative performance for one campaign, grouped by background
830
- video. Each child is one ad creative. This is a
831
- snapshot, not a date range. `startDate` and `endDate` are rejected.
1081
+ video. Each child is one ad creative. `timestamp_start_ms` and
1082
+ `timestamp_end_ms` are the audio cut in milliseconds when that cut is
1083
+ a ready sound for this organization. Otherwise both are null. Two cuts
1084
+ of the same track stay separate. This is a snapshot, not a date range.
1085
+ `startDate` and `endDate` are rejected.
832
1086
 
833
1087
  Spend is omitted until media spend and fees can be split. Ratios use
834
1088
  the same lifetime basis as the Creatives tab.
@@ -864,6 +1118,8 @@ paths:
864
1118
  - caption: Late night version
865
1119
  language: en
866
1120
  spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1121
+ timestamp_start_ms: 45000
1122
+ timestamp_end_ms: 60000
867
1123
  listeners: 200
868
1124
  followers: 40
869
1125
  link_clicks: 120
@@ -874,6 +1130,8 @@ paths:
874
1130
  - caption: Daytime version
875
1131
  language: en
876
1132
  spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1133
+ timestamp_start_ms: 0
1134
+ timestamp_end_ms: 15000
877
1135
  listeners: 200
878
1136
  followers: 40
879
1137
  link_clicks: 160
@@ -890,6 +1148,82 @@ paths:
890
1148
  '429': { $ref: '#/components/responses/RateLimited' }
891
1149
  '500': { $ref: '#/components/responses/InternalError' }
892
1150
 
1151
+ /v1/campaigns/{campaignId}/metrics/creative-daily:
1152
+ get:
1153
+ operationId: getCampaignCreativeDailyMetrics
1154
+ summary: Campaign creative daily metrics
1155
+ description: |
1156
+ Daily creative performance for one campaign. One row per day and
1157
+ current Meta ad creative. `spend_media` is Meta media spend. `cpf` is
1158
+ `spend_media / followers` for that row, and null when followers is zero.
1159
+ For a longer window, divide the summed spend by the summed followers.
1160
+ Do not average the daily `cpf` values.
1161
+
1162
+ The grain is the Meta ad creative, not the background-video groups from
1163
+ the lifetime creatives endpoint. That endpoint still rejects dates.
1164
+
1165
+ `startDate` and `endDate` are optional and inclusive. Omit both to
1166
+ return every day that has rows. Results are ordered by date, then
1167
+ creative id, and paginated.
1168
+
1169
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
1170
+ tags: [Metrics]
1171
+ security:
1172
+ - apiKeyBearerAuth: []
1173
+ - oauthBearer: []
1174
+ x-required-scope: metrics:read
1175
+ parameters:
1176
+ - $ref: '#/components/parameters/campaignId'
1177
+ - name: startDate
1178
+ in: query
1179
+ schema:
1180
+ type: string
1181
+ format: date
1182
+ description: Inclusive start date (`YYYY-MM-DD`). Omit to include every day from the first row.
1183
+ - name: endDate
1184
+ in: query
1185
+ schema:
1186
+ type: string
1187
+ format: date
1188
+ description: Inclusive end date (`YYYY-MM-DD`). Omit to include every day through the latest row.
1189
+ - $ref: '#/components/parameters/page'
1190
+ - $ref: '#/components/parameters/pageSize500'
1191
+ responses:
1192
+ '200':
1193
+ description: Daily creative rows for the campaign
1194
+ content:
1195
+ application/json:
1196
+ schema:
1197
+ $ref: '#/components/schemas/CreativeDailyMetricsResponse'
1198
+ example:
1199
+ data:
1200
+ items:
1201
+ - date: '2026-03-01'
1202
+ meta_ad_creative_id: '1234567890'
1203
+ spend_media: 40
1204
+ impressions: 400
1205
+ followers: 4
1206
+ cpf: 10
1207
+ - date: '2026-03-02'
1208
+ meta_ad_creative_id: '1234567890'
1209
+ spend_media: 10.5
1210
+ impressions: 100
1211
+ followers: 0
1212
+ cpf: null
1213
+ pagination:
1214
+ page: 1
1215
+ pageSize: 50
1216
+ totalCount: 2
1217
+ totalPages: 1
1218
+ meta:
1219
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1220
+ '400': { $ref: '#/components/responses/BadRequest' }
1221
+ '401': { $ref: '#/components/responses/Unauthorized' }
1222
+ '403': { $ref: '#/components/responses/Forbidden' }
1223
+ '404': { $ref: '#/components/responses/NotFound' }
1224
+ '429': { $ref: '#/components/responses/RateLimited' }
1225
+ '500': { $ref: '#/components/responses/InternalError' }
1226
+
893
1227
  /v1/campaigns/{campaignId}/metrics/breakdown:
894
1228
  get:
895
1229
  operationId: getCampaignMetricsBreakdown
@@ -932,18 +1266,18 @@ paths:
932
1266
  - $ref: '#/components/parameters/sortOrder'
933
1267
  responses:
934
1268
  '200':
935
- description: Paginated per-day country rows (`campaign_country_daily` schema)
1269
+ description: Paginated per-day country rows (`campaign_country_daily` schema v1.1)
936
1270
  content:
937
1271
  application/json:
938
1272
  schema:
939
1273
  $ref: '#/components/schemas/MetricsBreakdownResponse'
940
1274
  example:
941
1275
  data:
942
- schemaVersion: '1.0'
1276
+ schemaVersion: '1.1'
943
1277
  items:
944
1278
  - provider: soundlink
945
1279
  account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
946
- schema_version: '1.0'
1280
+ schema_version: '1.1'
947
1281
  report_date: '2026-04-01'
948
1282
  report_date_timezone: UTC
949
1283
  exported_at: '2026-05-20T03:00:00Z'
@@ -959,8 +1293,11 @@ paths:
959
1293
  link_clicks: 89
960
1294
  streams: 203
961
1295
  listeners: 145
1296
+ new_listeners: 145
1297
+ returning_listeners: 40
1298
+ total_listeners: 185
962
1299
  followers: 12
963
- streams_per_listener: 1.4
1300
+ streams_per_listener: 1.1
964
1301
  spend_media: 42.50
965
1302
  spend_total: 53.13
966
1303
  fees: 10.63
@@ -1048,8 +1385,8 @@ paths:
1048
1385
  schema:
1049
1386
  $ref: '#/components/schemas/BreakdownRow'
1050
1387
  example: |
1051
- {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","campaign_target_playlist_id":null,"country_code":"US","impressions":4821,"ad_clicks":112,"link_clicks":89,"streams":203,"listeners":145,"followers":12,"streams_per_listener":1.4,"spend_media":42.50,"spend_total":53.13,"fees":10.63,"currency":"USD","currency_account":"USD","cpl":0.293,"cpf":3.542,"cpc_linkclick":0.478,"ctr_linkclick":0.0185,"ctr_adclick":0.0232,"cost_per_result":3.542,"result_type":"follow"}
1052
- {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","campaign_target_playlist_id":null,"country_code":"DE","impressions":2103,"ad_clicks":48,"link_clicks":31,"streams":87,"listeners":61,"followers":4,"streams_per_listener":1.43,"spend_media":18.20,"spend_total":22.75,"fees":4.55,"currency":"USD","currency_account":"USD","cpl":0.298,"cpf":4.55,"cpc_linkclick":0.587,"ctr_linkclick":0.0148,"ctr_adclick":0.0228,"cost_per_result":4.55,"result_type":"follow"}
1388
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.1","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","campaign_target_playlist_id":null,"country_code":"US","impressions":4821,"ad_clicks":112,"link_clicks":89,"streams":203,"listeners":145,"new_listeners":145,"returning_listeners":40,"total_listeners":185,"followers":12,"streams_per_listener":1.1,"spend_media":42.50,"spend_total":53.13,"fees":10.63,"currency":"USD","currency_account":"USD","cpl":0.293,"cpf":3.542,"cpc_linkclick":0.478,"ctr_linkclick":0.0185,"ctr_adclick":0.0232,"cost_per_result":3.542,"result_type":"follow"}
1389
+ {"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.1","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","campaign_target_playlist_id":null,"country_code":"DE","impressions":2103,"ad_clicks":48,"link_clicks":31,"streams":87,"listeners":61,"new_listeners":61,"returning_listeners":12,"total_listeners":73,"followers":4,"streams_per_listener":1.19,"spend_media":18.20,"spend_total":22.75,"fees":4.55,"currency":"USD","currency_account":"USD","cpl":0.298,"cpf":4.55,"cpc_linkclick":0.587,"ctr_linkclick":0.0148,"ctr_adclick":0.0228,"cost_per_result":4.55,"result_type":"follow"}
1053
1390
  '400': { $ref: '#/components/responses/BadRequest' }
1054
1391
  '401': { $ref: '#/components/responses/Unauthorized' }
1055
1392
  '403': { $ref: '#/components/responses/Forbidden' }
@@ -1248,6 +1585,122 @@ paths:
1248
1585
  '429': { $ref: '#/components/responses/RateLimited' }
1249
1586
  '500': { $ref: '#/components/responses/InternalError' }
1250
1587
 
1588
+ /v1/campaigns/{campaignId}/metrics/retention:
1589
+ get:
1590
+ operationId: getCampaignRetention
1591
+ summary: Campaign cohort retention
1592
+ description: |
1593
+ Cohort retention for a campaign's linked soundlink: one row per cohort date
1594
+ that has first plays (dates with no first plays have no row), where the
1595
+ cohort date is the UTC date listeners first played via the campaign soundlink.
1596
+ A listener's cohort date is their earliest first play across all countries.
1597
+ Conforms to the `soundlink_cohort_retention_daily` v1.0 schema (same row
1598
+ shape as `GET /v1/soundlinks/{soundlinkId}/metrics/retention`). All rows
1599
+ are returned in `data.items` (one per cohort date), so there is no
1600
+ pagination.
1601
+
1602
+ The campaign's `smart_link_id` is resolved from `dim_campaigns_current`
1603
+ before the retention query runs.
1604
+
1605
+ **Retention definitions:**
1606
+ - `returned_on_day_N`: listeners from the cohort who played again on exactly day N
1607
+ after their first play.
1608
+ - `retention_by_day_N`: share of the cohort (`cohort_size`) who played again on any
1609
+ day from 1 to N (end-day, cumulative). Each listener is counted once, so the
1610
+ by-day rate never decreases within a row.
1611
+ - A day-N value is `null` until day N has passed for that cohort date.
1612
+
1613
+ **Known limitation:** end-day rates are cumulative per listener, so whether
1614
+ day-3 returners also returned on day 2 is not recoverable from the end-day
1615
+ columns. Use the exact-day `returned_on_day_N` columns for day-by-day behaviour.
1616
+
1617
+ `soundlink_target_isrc` is currently always `null`.
1618
+
1619
+ **Date range:** `startDate` / `endDate` filter the cohort date (both inclusive).
1620
+ If you omit both, a recent window ending today is used. A range that is too wide
1621
+ returns `400 invalid_query_parameter`.
1622
+
1623
+ **Plan requirement:** Label, Enterprise, committed, and self-serve plans.
1624
+ Organizations on a lower plan receive `403 premium_plan_required`.
1625
+
1626
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
1627
+ A campaign outside the organization returns `404 campaign_not_found`.
1628
+ An owned campaign with no linked soundlink in `dim_campaigns_current`
1629
+ returns `404 not_found` (`Campaign soundlink not found.`).
1630
+ tags: [Metrics]
1631
+ security:
1632
+ - apiKeyBearerAuth: []
1633
+ - oauthBearer: []
1634
+ x-required-scope: metrics:read
1635
+ x-premium-plan-level-min: 3
1636
+ parameters:
1637
+ - $ref: '#/components/parameters/campaignId'
1638
+ - $ref: '#/components/parameters/startDate'
1639
+ - $ref: '#/components/parameters/endDate'
1640
+ responses:
1641
+ '200':
1642
+ description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` ascending.
1643
+ content:
1644
+ application/json:
1645
+ schema:
1646
+ $ref: '#/components/schemas/SoundlinkCohortRetentionResponse'
1647
+ '400': { $ref: '#/components/responses/BadRequest' }
1648
+ '401': { $ref: '#/components/responses/Unauthorized' }
1649
+ '403': { $ref: '#/components/responses/PremiumAnalyticsForbidden' }
1650
+ '404': { $ref: '#/components/responses/NotFound' }
1651
+ '429': { $ref: '#/components/responses/RateLimited' }
1652
+ '500': { $ref: '#/components/responses/InternalError' }
1653
+
1654
+ /v1/campaigns/{campaignId}/listening-insights/{insight}:
1655
+ get:
1656
+ operationId: getCampaignListeningInsight
1657
+ summary: Campaign listening insights
1658
+ description: |
1659
+ What listeners who connected through this campaign went on to play.
1660
+ The date window comes from the listening graph (`nodes_smart_link`).
1661
+ `startDate` and `endDate` are not accepted. Extra query parameters are ignored.
1662
+
1663
+ This request often takes 30–50 seconds. Use a client timeout of at least 120 seconds.
1664
+ If the API Gateway deadline elapses, the response is `504`. That body is the gateway error, not the Public API envelope.
1665
+
1666
+ - `other-artists` — other artists these listeners streamed, excluding attributed tracks and campaign artists. Top 30.
1667
+ - `catalog-dig-in` — playlist reach and catalog follow-through per artist. Track campaigns may return `artists: []`.
1668
+ - `stream-split` — `track` campaigns return attributed contexts such as `promoted` and `artist_catalog`. `playlist` campaigns return `playlist` then `artist_catalog`. A context is omitted when listeners and streams are both 0. Any other campaign type returns `200` with `contexts: []`.
1669
+
1670
+ **Plan requirement:** Label, Enterprise, committed, and self-serve plans.
1671
+ Organizations on a lower plan receive `403 premium_plan_required`.
1672
+
1673
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
1674
+ A campaign outside the organization returns `404 campaign_not_found`.
1675
+ An owned campaign with no listening-graph row returns `404 not_in_listening_graph`
1676
+ (`Soundlink not available in listening graph`).
1677
+ tags: [Metrics]
1678
+ security:
1679
+ - apiKeyBearerAuth: []
1680
+ - oauthBearer: []
1681
+ x-required-scope: metrics:read
1682
+ x-premium-plan-level-min: 3
1683
+ x-recommended-timeout-seconds: 120
1684
+ parameters:
1685
+ - $ref: '#/components/parameters/campaignId'
1686
+ - $ref: '#/components/parameters/listeningInsight'
1687
+ responses:
1688
+ '200':
1689
+ description: Listening insight for the campaign soundlink window. The `data.insight` value matches the path.
1690
+ content:
1691
+ application/json:
1692
+ schema:
1693
+ $ref: '#/components/schemas/ListeningInsightsResponse'
1694
+ '400': { $ref: '#/components/responses/BadRequest' }
1695
+ '401': { $ref: '#/components/responses/Unauthorized' }
1696
+ '403': { $ref: '#/components/responses/PremiumAnalyticsForbidden' }
1697
+ '404': { $ref: '#/components/responses/NotFound' }
1698
+ '429': { $ref: '#/components/responses/RateLimited' }
1699
+ '500': { $ref: '#/components/responses/InternalError' }
1700
+ '504':
1701
+ description: |
1702
+ The API Gateway deadline of 120 seconds elapsed. The body is the gateway error, not the Public API envelope (`data` or `error`, plus `meta`).
1703
+
1251
1704
  /v1/soundlinks:
1252
1705
  get:
1253
1706
  operationId: listSoundlinks
@@ -1315,7 +1768,8 @@ paths:
1315
1768
  API equivalent of the in-app create flow. It does not create a wallet
1316
1769
  campaign and does not appear on `GET /v1/campaigns`.
1317
1770
 
1318
- Requires the `soundlinks:write` scope.
1771
+ Requires the `soundlinks:write` scope and a self-serve plan on the
1772
+ organization; otherwise returns `403 soundlink_plan_required`.
1319
1773
 
1320
1774
  `Idempotency-Key` is **required**. Reusing the key with an unchanged
1321
1775
  body replays the original `201`; a different body returns
@@ -1343,6 +1797,7 @@ paths:
1343
1797
  spotifyUrl: 'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl'
1344
1798
  autoFollow: true
1345
1799
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1800
+ attributionEnabled: true
1346
1801
  metaPixelId: '1234567890123456'
1347
1802
  metaConversionAccessToken: 'EAAB...'
1348
1803
  playlist:
@@ -1369,6 +1824,7 @@ paths:
1369
1824
  createdAt: '2026-04-01T10:00:00Z'
1370
1825
  autoFollow: true
1371
1826
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1827
+ attributionEnabled: true
1372
1828
  metaPixelId: '1234567890123456'
1373
1829
  tiktokPixelId: null
1374
1830
  appleMusicUrl: null
@@ -1418,6 +1874,7 @@ paths:
1418
1874
  createdAt: '2026-04-01T10:00:00Z'
1419
1875
  autoFollow: true
1420
1876
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1877
+ attributionEnabled: true
1421
1878
  metaPixelId: '1234567890123456'
1422
1879
  tiktokPixelId: null
1423
1880
  appleMusicUrl: null
@@ -1466,6 +1923,7 @@ paths:
1466
1923
  createdAt: '2026-04-01T10:00:00Z'
1467
1924
  autoFollow: true
1468
1925
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1926
+ attributionEnabled: true
1469
1927
  metaPixelId: '1234567890123456'
1470
1928
  tiktokPixelId: null
1471
1929
  appleMusicUrl: null
@@ -1926,51 +2384,162 @@ paths:
1926
2384
  '429': { $ref: '#/components/responses/RateLimited' }
1927
2385
  '500': { $ref: '#/components/responses/InternalError' }
1928
2386
 
1929
- /v1/videos/import:
1930
- post:
1931
- operationId: importVideo
1932
- summary: Import video(s) from public HTTPS MP4 or QuickTime URL(s)
2387
+ /v1/soundlinks/{soundlinkId}/metrics/retention:
2388
+ get:
2389
+ operationId: getSoundlinkRetention
2390
+ summary: Soundlink cohort retention
1933
2391
  description: |
1934
- Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
1935
- session, enqueues async download/staging, and returns `202` with `sessionId`.
1936
- URLs may be MP4 (`video/mp4`) or QuickTime (`.mov` / `video/quicktime`).
1937
- Unsupported types return `invalid_video_content_type`.
1938
- QuickTime imports stay `processing` while they transcode to MP4, then
1939
- follow the same ingest path as native MP4.
2392
+ Cohort retention for a soundlink: one row per cohort date that has first
2393
+ plays (dates with no first plays have no row), where the cohort date is
2394
+ the UTC date listeners first played via the soundlink. A listener's
2395
+ cohort date is their earliest first play across all countries.
2396
+ Conforms to the `soundlink_cohort_retention_daily` v1.0 schema. All rows
2397
+ are returned in `data.items` (one per cohort date), so there is no
2398
+ pagination.
2399
+
2400
+ **Retention definitions:**
2401
+ - `returned_on_day_N`: listeners from the cohort who played again on exactly day N
2402
+ after their first play.
2403
+ - `retention_by_day_N`: share of the cohort (`cohort_size`) who played again on any
2404
+ day from 1 to N (end-day, cumulative). Each listener is counted once, so the
2405
+ by-day rate never decreases within a row.
2406
+ - A day-N value is `null` until day N has passed for that cohort date.
2407
+
2408
+ **Known limitation:** end-day rates are cumulative per listener, so whether
2409
+ day-3 returners also returned on day 2 is not recoverable from the end-day
2410
+ columns. Use the exact-day `returned_on_day_N` columns for day-by-day behaviour.
2411
+
2412
+ `soundlink_target_isrc` is currently always `null`.
2413
+
2414
+ **Date range:** `startDate` / `endDate` filter the cohort date (both inclusive).
2415
+ If you omit both, a recent window ending today is used. A range that is too wide
2416
+ returns `400 invalid_query_parameter`.
2417
+
2418
+ **Plan requirement:** Label, Enterprise, committed, and self-serve plans.
2419
+ Organizations on a lower plan receive `403 premium_plan_required`.
1940
2420
 
1941
- Requires the `videos:write` scope. Subject to a stricter per-credential rate
1942
- limit than generic public API routes (default 20 imports per hour per API key
1943
- or OAuth grant). This caps how many import requests are accepted per hour,
1944
- not how long ingestion takes.
1945
-
1946
- Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready`, `partial`,
1947
- or `failed`. For single-URL imports, use `videoId` when ready. For batches
1948
- (`count > 1`), use `videoIds`.
1949
- tags: [Videos]
2421
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
2422
+ tags: [Soundlinks]
1950
2423
  security:
1951
2424
  - apiKeyBearerAuth: []
1952
2425
  - oauthBearer: []
1953
- x-required-scope: videos:write
1954
- requestBody:
1955
- required: true
1956
- content:
1957
- application/json:
1958
- schema:
1959
- $ref: '#/components/schemas/VideoImportRequest'
1960
- examples:
1961
- single:
1962
- summary: Single URL (legacy)
1963
- value:
1964
- url: 'https://cdn.example.com/promo.mp4'
1965
- batch:
1966
- summary: Batch of URLs
1967
- value:
1968
- videos:
1969
- - url: 'https://cdn.example.com/a.mp4'
1970
- - url: 'https://cdn.example.com/b.mov'
1971
- responses:
1972
- '200':
1973
- description: Duplicate video already in the organization's library (sync legacy path only)
2426
+ x-required-scope: soundlinks:read
2427
+ x-premium-plan-level-min: 3
2428
+ parameters:
2429
+ - $ref: '#/components/parameters/soundlinkId'
2430
+ - $ref: '#/components/parameters/startDate'
2431
+ - $ref: '#/components/parameters/endDate'
2432
+ responses:
2433
+ '200':
2434
+ description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` ascending.
2435
+ content:
2436
+ application/json:
2437
+ schema:
2438
+ $ref: '#/components/schemas/SoundlinkCohortRetentionResponse'
2439
+ '400': { $ref: '#/components/responses/BadRequest' }
2440
+ '401': { $ref: '#/components/responses/Unauthorized' }
2441
+ '403': { $ref: '#/components/responses/PremiumAnalyticsForbidden' }
2442
+ '404': { $ref: '#/components/responses/NotFound' }
2443
+ '429': { $ref: '#/components/responses/RateLimited' }
2444
+ '500': { $ref: '#/components/responses/InternalError' }
2445
+
2446
+ /v1/soundlinks/{soundlinkId}/listening-insights/{insight}:
2447
+ get:
2448
+ operationId: getSoundlinkListeningInsight
2449
+ summary: Soundlink listening insights
2450
+ description: |
2451
+ What listeners who connected through this soundlink went on to play.
2452
+ The date window comes from the listening graph (`nodes_smart_link`).
2453
+ `startDate` and `endDate` are not accepted. Extra query parameters are ignored.
2454
+
2455
+ This request often takes 30–50 seconds. Use a client timeout of at least 120 seconds.
2456
+ If the API Gateway deadline elapses, the response is `504`. That body is the gateway error, not the Public API envelope.
2457
+
2458
+ - `other-artists` — other artists these listeners streamed, excluding attributed tracks and campaign artists. Top 30.
2459
+ - `catalog-dig-in` — playlist reach and catalog follow-through per artist. Track soundlinks may return `artists: []`.
2460
+ - `stream-split` — `track` soundlinks return attributed contexts such as `promoted` and `artist_catalog`. `playlist` soundlinks return `playlist` then `artist_catalog`. A context is omitted when listeners and streams are both 0. Any other campaign type returns `200` with `contexts: []`.
2461
+
2462
+ **Plan requirement:** Label, Enterprise, committed, and self-serve plans.
2463
+ Organizations on a lower plan receive `403 premium_plan_required`.
2464
+
2465
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
2466
+ A soundlink created for a campaign is allowed here when the organization owns it,
2467
+ even though `GET /v1/soundlinks/{soundlinkId}` does not return campaign soundlinks.
2468
+ An unknown soundlink, or one owned by another organization, returns `404 not_found`.
2469
+ An owned soundlink with no listening-graph row returns `404 not_in_listening_graph`
2470
+ (`Soundlink not available in listening graph`).
2471
+ tags: [Soundlinks]
2472
+ security:
2473
+ - apiKeyBearerAuth: []
2474
+ - oauthBearer: []
2475
+ x-required-scope: soundlinks:read
2476
+ x-premium-plan-level-min: 3
2477
+ x-recommended-timeout-seconds: 120
2478
+ parameters:
2479
+ - $ref: '#/components/parameters/soundlinkId'
2480
+ - $ref: '#/components/parameters/listeningInsight'
2481
+ responses:
2482
+ '200':
2483
+ description: Listening insight for the soundlink window. The `data.insight` value matches the path.
2484
+ content:
2485
+ application/json:
2486
+ schema:
2487
+ $ref: '#/components/schemas/ListeningInsightsResponse'
2488
+ '400': { $ref: '#/components/responses/BadRequest' }
2489
+ '401': { $ref: '#/components/responses/Unauthorized' }
2490
+ '403': { $ref: '#/components/responses/PremiumAnalyticsForbidden' }
2491
+ '404': { $ref: '#/components/responses/NotFound' }
2492
+ '429': { $ref: '#/components/responses/RateLimited' }
2493
+ '500': { $ref: '#/components/responses/InternalError' }
2494
+ '504':
2495
+ description: |
2496
+ The API Gateway deadline of 120 seconds elapsed. The body is the gateway error, not the Public API envelope (`data` or `error`, plus `meta`).
2497
+
2498
+ /v1/videos/import:
2499
+ post:
2500
+ operationId: importVideo
2501
+ summary: Import video(s) from public HTTPS MP4 or QuickTime URL(s)
2502
+ description: |
2503
+ Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
2504
+ session, enqueues async download/staging, and returns `202` with `sessionId`.
2505
+ URLs may be MP4 (`video/mp4`) or QuickTime (`.mov` / `video/quicktime`).
2506
+ Unsupported types return `invalid_video_content_type`.
2507
+ QuickTime imports stay `processing` while they transcode to MP4, then
2508
+ follow the same ingest path as native MP4.
2509
+
2510
+ Requires the `videos:write` scope. Subject to a stricter per-credential rate
2511
+ limit than generic public API routes (default 20 imports per hour per API key
2512
+ or OAuth grant). This caps how many import requests are accepted per hour,
2513
+ not how long ingestion takes.
2514
+
2515
+ Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready`, `partial`,
2516
+ or `failed`. For single-URL imports, use `videoId` when ready. For batches
2517
+ (`count > 1`), use `videoIds`.
2518
+ tags: [Videos]
2519
+ security:
2520
+ - apiKeyBearerAuth: []
2521
+ - oauthBearer: []
2522
+ x-required-scope: videos:write
2523
+ requestBody:
2524
+ required: true
2525
+ content:
2526
+ application/json:
2527
+ schema:
2528
+ $ref: '#/components/schemas/VideoImportRequest'
2529
+ examples:
2530
+ single:
2531
+ summary: Single URL (legacy)
2532
+ value:
2533
+ url: 'https://cdn.example.com/promo.mp4'
2534
+ batch:
2535
+ summary: Batch of URLs
2536
+ value:
2537
+ videos:
2538
+ - url: 'https://cdn.example.com/a.mp4'
2539
+ - url: 'https://cdn.example.com/b.mov'
2540
+ responses:
2541
+ '200':
2542
+ description: Duplicate video already in the organization's library (sync legacy path only)
1974
2543
  content:
1975
2544
  application/json:
1976
2545
  schema:
@@ -2052,6 +2621,18 @@ components:
2052
2621
  type: string
2053
2622
  description: Campaign identifier (UUID)
2054
2623
 
2624
+ listeningInsight:
2625
+ name: insight
2626
+ in: path
2627
+ required: true
2628
+ schema:
2629
+ type: string
2630
+ enum: [other-artists, catalog-dig-in, stream-split]
2631
+ description: |
2632
+ `other-artists` — what else these listeners stream.
2633
+ `catalog-dig-in` — playlist artists and catalog follow-through.
2634
+ `stream-split` — promoted, playlist, and artist-catalog split.
2635
+
2055
2636
  idempotencyKey:
2056
2637
  name: Idempotency-Key
2057
2638
  in: header
@@ -2191,6 +2772,74 @@ components:
2191
2772
  meta:
2192
2773
  $ref: '#/components/schemas/Meta'
2193
2774
 
2775
+ # --- Pixels ---
2776
+
2777
+ PixelPlatform:
2778
+ type: string
2779
+ enum: [meta]
2780
+ description: Ad platform for the pixel. Only `meta` is supported today.
2781
+
2782
+ Pixel:
2783
+ type: object
2784
+ required: [id, platform]
2785
+ properties:
2786
+ id:
2787
+ type: string
2788
+ platform:
2789
+ $ref: '#/components/schemas/PixelPlatform'
2790
+
2791
+ PixelListResponse:
2792
+ type: object
2793
+ required: [data, meta]
2794
+ properties:
2795
+ data:
2796
+ type: object
2797
+ required: [pixels]
2798
+ properties:
2799
+ pixels:
2800
+ type: array
2801
+ items:
2802
+ $ref: '#/components/schemas/Pixel'
2803
+ description: Pixels configured for the organization. Empty when none is saved.
2804
+ meta:
2805
+ $ref: '#/components/schemas/Meta'
2806
+
2807
+ UpdatePixelRequest:
2808
+ type: object
2809
+ required: [platform, accessToken]
2810
+ properties:
2811
+ platform:
2812
+ $ref: '#/components/schemas/PixelPlatform'
2813
+ accessToken:
2814
+ type: string
2815
+ minLength: 1
2816
+ description: Conversions API access token. Stored and never returned.
2817
+
2818
+ UpdatePixelResponse:
2819
+ type: object
2820
+ required: [data, meta]
2821
+ properties:
2822
+ data:
2823
+ $ref: '#/components/schemas/Pixel'
2824
+ meta:
2825
+ $ref: '#/components/schemas/Meta'
2826
+
2827
+ PixelTestEventResponse:
2828
+ type: object
2829
+ required: [data, meta]
2830
+ properties:
2831
+ data:
2832
+ type: object
2833
+ required: [status, pixelId]
2834
+ properties:
2835
+ status:
2836
+ type: string
2837
+ enum: [sent]
2838
+ pixelId:
2839
+ type: string
2840
+ meta:
2841
+ $ref: '#/components/schemas/Meta'
2842
+
2194
2843
  Pagination:
2195
2844
  type: object
2196
2845
  required: [page, pageSize, totalCount, totalPages]
@@ -2204,6 +2853,145 @@ components:
2204
2853
  totalPages:
2205
2854
  type: integer
2206
2855
 
2856
+ ListeningInsightWindow:
2857
+ type: object
2858
+ required: [startDate, endDate]
2859
+ properties:
2860
+ startDate:
2861
+ type: string
2862
+ format: date
2863
+ example: '2026-07-30'
2864
+ endDate:
2865
+ type: string
2866
+ format: date
2867
+ example: '2026-09-29'
2868
+
2869
+ OtherArtistsListeningInsight:
2870
+ type: object
2871
+ required: [soundlinkId, campaignId, insight, window, artists]
2872
+ properties:
2873
+ soundlinkId:
2874
+ type: string
2875
+ campaignId:
2876
+ type: string
2877
+ nullable: true
2878
+ insight:
2879
+ type: string
2880
+ enum: [other-artists]
2881
+ window:
2882
+ $ref: '#/components/schemas/ListeningInsightWindow'
2883
+ artists:
2884
+ type: array
2885
+ maxItems: 30
2886
+ items:
2887
+ type: object
2888
+ required: [artist, listeners, streams]
2889
+ properties:
2890
+ artist:
2891
+ type: string
2892
+ description: Lowercased, trimmed artist name.
2893
+ listeners:
2894
+ type: number
2895
+ streams:
2896
+ type: number
2897
+
2898
+ CatalogDigInListeningInsight:
2899
+ type: object
2900
+ required: [soundlinkId, campaignId, insight, window, artists]
2901
+ properties:
2902
+ soundlinkId:
2903
+ type: string
2904
+ campaignId:
2905
+ type: string
2906
+ nullable: true
2907
+ insight:
2908
+ type: string
2909
+ enum: [catalog-dig-in]
2910
+ window:
2911
+ $ref: '#/components/schemas/ListeningInsightWindow'
2912
+ artists:
2913
+ type: array
2914
+ maxItems: 30
2915
+ items:
2916
+ type: object
2917
+ required:
2918
+ - artist
2919
+ - playlistListeners
2920
+ - playlistStreams
2921
+ - catalogListeners
2922
+ - catalogStreams
2923
+ - catalogTracks
2924
+ - catalogListenerRate
2925
+ properties:
2926
+ artist:
2927
+ type: string
2928
+ playlistListeners:
2929
+ type: number
2930
+ playlistStreams:
2931
+ type: number
2932
+ catalogListeners:
2933
+ type: number
2934
+ catalogStreams:
2935
+ type: number
2936
+ catalogTracks:
2937
+ type: number
2938
+ catalogListenerRate:
2939
+ type: number
2940
+ nullable: true
2941
+ description: catalogListeners / playlistListeners. Null when playlistListeners is 0.
2942
+
2943
+ StreamSplitContext:
2944
+ type: object
2945
+ required: [engagementContext, listeners, streams, tracks]
2946
+ properties:
2947
+ engagementContext:
2948
+ type: string
2949
+ description: '`promoted`, `playlist`, or `artist_catalog`.'
2950
+ listeners:
2951
+ type: number
2952
+ streams:
2953
+ type: number
2954
+ tracks:
2955
+ type: number
2956
+
2957
+ StreamSplitListeningInsight:
2958
+ type: object
2959
+ required: [soundlinkId, campaignId, insight, window, contexts]
2960
+ properties:
2961
+ soundlinkId:
2962
+ type: string
2963
+ campaignId:
2964
+ type: string
2965
+ nullable: true
2966
+ insight:
2967
+ type: string
2968
+ enum: [stream-split]
2969
+ window:
2970
+ $ref: '#/components/schemas/ListeningInsightWindow'
2971
+ contexts:
2972
+ type: array
2973
+ description: Empty when the graph `campaign_type` is neither `track` nor `playlist`. The response is still `200`.
2974
+ items:
2975
+ $ref: '#/components/schemas/StreamSplitContext'
2976
+
2977
+ ListeningInsightsResponse:
2978
+ type: object
2979
+ required: [data, meta]
2980
+ properties:
2981
+ data:
2982
+ oneOf:
2983
+ - $ref: '#/components/schemas/OtherArtistsListeningInsight'
2984
+ - $ref: '#/components/schemas/CatalogDigInListeningInsight'
2985
+ - $ref: '#/components/schemas/StreamSplitListeningInsight'
2986
+ discriminator:
2987
+ propertyName: insight
2988
+ mapping:
2989
+ other-artists: '#/components/schemas/OtherArtistsListeningInsight'
2990
+ catalog-dig-in: '#/components/schemas/CatalogDigInListeningInsight'
2991
+ stream-split: '#/components/schemas/StreamSplitListeningInsight'
2992
+ meta:
2993
+ $ref: '#/components/schemas/Meta'
2994
+
2207
2995
  Error:
2208
2996
  type: object
2209
2997
  required: [code, message]
@@ -2213,10 +3001,13 @@ components:
2213
3001
  description: Stable snake_case error code.
2214
3002
  enum:
2215
3003
  - invalid_api_key
3004
+ - invalid_token
2216
3005
  - api_key_revoked
2217
3006
  - api_key_expired
3007
+ - access_denied
2218
3008
  - insufficient_scope
2219
3009
  - not_found
3010
+ - not_in_listening_graph
2220
3011
  - campaign_not_found
2221
3012
  - invalid_query_parameter
2222
3013
  - invalid_date_range
@@ -2229,8 +3020,14 @@ components:
2229
3020
  - invalid_spotify_url
2230
3021
  - invalid_tier_budget_allocation
2231
3022
  - invalid_tier_status
2232
- - tier_update_cooldown
3023
+ - learning_edit_ack_required
2233
3024
  - wallet_not_enabled
3025
+ - premium_plan_required
3026
+ - youtube_music_not_enabled
3027
+ - attribution_not_enabled
3028
+ - soundlink_plan_required
3029
+ - custom_pixel_not_enabled
3030
+ - meta_pixel_conflict
2234
3031
  - insufficient_credit
2235
3032
  - idempotency_key_conflict
2236
3033
  - rate_limit_exceeded
@@ -2389,6 +3186,14 @@ components:
2389
3186
  description: |
2390
3187
  Whether this wallet campaign renews at the end of each cycle.
2391
3188
  `false` when auto-renew is off or the campaign has no stored value.
3189
+ nextRenewalAt:
3190
+ type: string
3191
+ format: date-time
3192
+ nullable: true
3193
+ description: |
3194
+ When the current wallet cycle ends and the campaign renews.
3195
+ `null` unless the campaign is wallet-funded, auto-renew is on,
3196
+ and a cycle end is stored.
2392
3197
 
2393
3198
  CampaignListResponse:
2394
3199
  type: object
@@ -2418,7 +3223,7 @@ components:
2418
3223
 
2419
3224
  CampaignTier:
2420
3225
  type: object
2421
- required: [tierId, tierName, isEnabled, allocationPercent]
3226
+ required: [tierId, tierName, isEnabled, allocationPercent, learningStatus]
2422
3227
  properties:
2423
3228
  tierId:
2424
3229
  type: integer
@@ -2434,6 +3239,13 @@ components:
2434
3239
  minimum: 0
2435
3240
  maximum: 100
2436
3241
  description: Share of campaign budget allocated to this tier.
3242
+ learningStatus:
3243
+ type: string
3244
+ nullable: true
3245
+ enum: [LEARNING, FAIL, SUCCESS]
3246
+ description: |
3247
+ Stored ad set learning status for this tier. `null` means no status
3248
+ is stored and does not require acknowledgement before a tier edit.
2437
3249
 
2438
3250
  CampaignTiersData:
2439
3251
  type: object
@@ -2460,6 +3272,41 @@ components:
2460
3272
  meta:
2461
3273
  $ref: '#/components/schemas/Meta'
2462
3274
 
3275
+ CampaignActivityItem:
3276
+ type: object
3277
+ required: [event_type, timestamp, summary]
3278
+ properties:
3279
+ event_type:
3280
+ type: string
3281
+ description: Activity event type.
3282
+ timestamp:
3283
+ type: string
3284
+ format: date-time
3285
+ description: When the event was recorded.
3286
+ summary:
3287
+ type: string
3288
+ description: Short description. Omits fees, payment ids, and file URIs.
3289
+
3290
+ CampaignActivityData:
3291
+ type: object
3292
+ required: [items, pagination]
3293
+ properties:
3294
+ items:
3295
+ type: array
3296
+ items:
3297
+ $ref: '#/components/schemas/CampaignActivityItem'
3298
+ pagination:
3299
+ $ref: '#/components/schemas/Pagination'
3300
+
3301
+ CampaignActivityResponse:
3302
+ type: object
3303
+ required: [data, meta]
3304
+ properties:
3305
+ data:
3306
+ $ref: '#/components/schemas/CampaignActivityData'
3307
+ meta:
3308
+ $ref: '#/components/schemas/Meta'
3309
+
2463
3310
  TierStatusUpdateItem:
2464
3311
  type: object
2465
3312
  required: [targetingTierId, isEnabled, newAllocationPercent]
@@ -2486,6 +3333,11 @@ components:
2486
3333
  minItems: 1
2487
3334
  items:
2488
3335
  $ref: '#/components/schemas/TierStatusUpdateItem'
3336
+ acknowledgeLearningWarning:
3337
+ type: boolean
3338
+ description: |
3339
+ Set to true to continue a tier edit while ad sets are still learning.
3340
+ Omit or false to leave the warning unacknowledged.
2489
3341
 
2490
3342
  Genre:
2491
3343
  type: string
@@ -2905,12 +3757,15 @@ components:
2905
3757
  MetricsOverview:
2906
3758
  type: object
2907
3759
  description: |
2908
- Campaign-level totals aggregated across all countries for the requested
2909
- date range. Field names align with the `campaign_country_daily` row
2910
- schema — values here are the sum of country rows.
3760
+ Campaign-level totals for the requested date range. Spend, streams,
3761
+ followers, delivery, and `listeners` come from summing
3762
+ `campaign_country_daily` rows. `total_listeners` is distinct listeners
3763
+ in the window (same definition as the dashboard), so it is not the sum
3764
+ of daily `total_listeners` from breakdown rows.
2911
3765
  required:
2912
3766
  [
2913
3767
  listeners,
3768
+ total_listeners,
2914
3769
  streams,
2915
3770
  followers,
2916
3771
  spend_media,
@@ -2924,7 +3779,14 @@ components:
2924
3779
  properties:
2925
3780
  listeners:
2926
3781
  type: integer
2927
- description: Unique attributed Spotify listeners (sum of country rows).
3782
+ description: |
3783
+ Attributed new Spotify listeners in the window (dashboard Super
3784
+ Listeners). Same basis as `cpl`. Sum of country-day `listeners`.
3785
+ total_listeners:
3786
+ type: integer
3787
+ description: |
3788
+ Distinct listeners in the window (new + returning). Same basis as
3789
+ dashboard S/L. Not equal to the sum of breakdown `total_listeners`.
2928
3790
  streams:
2929
3791
  type: integer
2930
3792
  description: Attributed Spotify streams (sum of country rows).
@@ -2957,13 +3819,15 @@ components:
2957
3819
  description: Currency for spend fields. Currently always `USD`.
2958
3820
  cpl:
2959
3821
  type: number
2960
- description: Cost per listener (spend_media / listeners).
3822
+ description: Cost per new listener (spend_media / listeners).
2961
3823
  cpf:
2962
3824
  type: number
2963
3825
  description: Cost per follower (spend_media / followers).
2964
3826
  streams_per_listener:
2965
3827
  type: number
2966
- description: streams / listeners. Zero if listeners is zero.
3828
+ description: |
3829
+ streams / total_listeners. Matches dashboard S/L. Zero if
3830
+ total_listeners is zero.
2967
3831
 
2968
3832
  MetricsOverviewResponse:
2969
3833
  type: object
@@ -2980,6 +3844,8 @@ components:
2980
3844
  - caption
2981
3845
  - language
2982
3846
  - spotify_track_id
3847
+ - timestamp_start_ms
3848
+ - timestamp_end_ms
2983
3849
  - listeners
2984
3850
  - followers
2985
3851
  - link_clicks
@@ -2998,6 +3864,18 @@ components:
2998
3864
  spotify_track_id:
2999
3865
  type: string
3000
3866
  description: Spotify track id stored on the render. Not a lookup.
3867
+ timestamp_start_ms:
3868
+ type: integer
3869
+ nullable: true
3870
+ description: |
3871
+ Start of the audio cut in milliseconds from the beginning of the
3872
+ track. Null when the cut is not a ready sound for this organization.
3873
+ timestamp_end_ms:
3874
+ type: integer
3875
+ nullable: true
3876
+ description: |
3877
+ End of the audio cut in milliseconds. Null when the cut is not a
3878
+ ready sound for this organization.
3001
3879
  listeners:
3002
3880
  type: integer
3003
3881
  nullable: true
@@ -3087,10 +3965,61 @@ components:
3087
3965
  meta:
3088
3966
  $ref: '#/components/schemas/Meta'
3089
3967
 
3968
+ CreativeDailyMetricsRow:
3969
+ type: object
3970
+ required:
3971
+ - date
3972
+ - meta_ad_creative_id
3973
+ - spend_media
3974
+ - impressions
3975
+ - followers
3976
+ - cpf
3977
+ properties:
3978
+ date:
3979
+ type: string
3980
+ format: date
3981
+ description: UTC calendar date (`YYYY-MM-DD`).
3982
+ meta_ad_creative_id:
3983
+ type: string
3984
+ description: Current Meta ad creative. Ads that share this id are summed for the day.
3985
+ spend_media:
3986
+ type: number
3987
+ description: Meta media spend for the day. Fees are not included.
3988
+ impressions:
3989
+ type: number
3990
+ description: Meta impressions for the day.
3991
+ followers:
3992
+ type: number
3993
+ description: Follows attributed for the day.
3994
+ cpf:
3995
+ type: number
3996
+ nullable: true
3997
+ description: Cost per follower (`spend_media / followers`) for this row. Null when followers is zero.
3998
+
3999
+ CreativeDailyMetrics:
4000
+ type: object
4001
+ required: [items, pagination]
4002
+ properties:
4003
+ items:
4004
+ type: array
4005
+ items:
4006
+ $ref: '#/components/schemas/CreativeDailyMetricsRow'
4007
+ pagination:
4008
+ $ref: '#/components/schemas/Pagination'
4009
+
4010
+ CreativeDailyMetricsResponse:
4011
+ type: object
4012
+ required: [data, meta]
4013
+ properties:
4014
+ data:
4015
+ $ref: '#/components/schemas/CreativeDailyMetrics'
4016
+ meta:
4017
+ $ref: '#/components/schemas/Meta'
4018
+
3090
4019
  BreakdownRow:
3091
4020
  type: object
3092
4021
  description: |
3093
- One row of the `campaign_country_daily` v1.0 schema.
4022
+ One row of the `campaign_country_daily` v1.1 schema.
3094
4023
  Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
3095
4024
  Rows are idempotent — re-ingesting on the primary key is safe.
3096
4025
  Values for a given `report_date` may be revised for up to 7 days after
@@ -3108,6 +4037,9 @@ components:
3108
4037
  - country_code
3109
4038
  - streams
3110
4039
  - listeners
4040
+ - new_listeners
4041
+ - returning_listeners
4042
+ - total_listeners
3111
4043
  - followers
3112
4044
  - streams_per_listener
3113
4045
  - spend_media
@@ -3128,8 +4060,8 @@ components:
3128
4060
  description: Soundlink organization ID (UUID).
3129
4061
  schema_version:
3130
4062
  type: string
3131
- description: Schema version. Pin your ingest pipeline to this value.
3132
- example: '1.0'
4063
+ description: Schema version. Pin your ingest pipeline to this value. `1.1` adds listener splits.
4064
+ example: '1.1'
3133
4065
  report_date:
3134
4066
  type: string
3135
4067
  format: date
@@ -3185,13 +4117,28 @@ components:
3185
4117
  description: Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.
3186
4118
  listeners:
3187
4119
  type: integer
3188
- description: Unique Spotify listeners attributed to this campaign in this country on this day (7-day click-through window). Summing country rows gives the correct campaign-level total.
4120
+ description: |
4121
+ Attributed new Spotify listeners for this country-day (same as
4122
+ `new_listeners`). Basis for `cpl`.
4123
+ new_listeners:
4124
+ type: integer
4125
+ description: Alias of `listeners` (attributed new).
4126
+ returning_listeners:
4127
+ type: integer
4128
+ description: |
4129
+ Returning Spotify listeners for this country-day. Meta known-tier
4130
+ conversion rows are `0`.
4131
+ total_listeners:
4132
+ type: integer
4133
+ description: new_listeners + returning_listeners for this row.
3189
4134
  followers:
3190
4135
  type: integer
3191
4136
  description: Spotify artist follower gains attributed to this campaign in this country on this day (7-day click-through window).
3192
4137
  streams_per_listener:
3193
4138
  type: number
3194
- description: streams / listeners for this row. Zero if listeners is zero.
4139
+ description: |
4140
+ streams / total_listeners for this row. Zero if total_listeners is
4141
+ zero.
3195
4142
  spend_media:
3196
4143
  type: number
3197
4144
  description: Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In `currency`.
@@ -3209,7 +4156,7 @@ components:
3209
4156
  description: Account billing currency. Currently always `USD`. Will differ from `currency` once EUR delivery is available.
3210
4157
  cpl:
3211
4158
  type: number
3212
- description: Cost per listener (spend_media / listeners). Zero if listeners is zero.
4159
+ description: Cost per new listener (spend_media / listeners). Zero if listeners is zero.
3213
4160
  cpf:
3214
4161
  type: number
3215
4162
  description: Cost per follower (spend_media / followers). Zero if followers is zero.
@@ -3544,9 +4491,11 @@ components:
3544
4491
  (`/song/{slug}/{id}`), a catalog playlist (`pl.`), a library
3545
4492
  playlist (`pl.u-`), or an album share-sheet link with `?i={songId}`
3546
4493
  (stored as the canonical song URL). Host must be `music.apple.com`
3547
- with a two-letter storefront. URL shape is checked only; the
3548
- Apple catalog is not looked up. Omit to create a Spotify-only
3549
- soundlink.
4494
+ with a two-letter storefront. Songs and catalog playlists are
4495
+ verified in that storefront; missing content returns
4496
+ `400 invalid_request`.
4497
+ Provider outages or rate limits warn and allow create. Library
4498
+ playlists are format-checked only. Omit to leave Apple Music unset.
3550
4499
  example: https://music.apple.com/us/song/anti-hero/1645937493
3551
4500
  youtubeMusicUrl:
3552
4501
  type: string
@@ -3557,8 +4506,17 @@ components:
3557
4506
  `youtu.be/…`) or a playlist (`…/playlist?list=…`). Shorts,
3558
4507
  live, channel, and browse links are rejected. A video or
3559
4508
  playlist that does not exist on YouTube returns
3560
- `400 invalid_request`. Omit to leave YouTube Music unset.
4509
+ `400 invalid_request`. Quota, auth, or upstream failures warn and
4510
+ allow create. Omit to leave YouTube Music unset.
3561
4511
  example: https://music.youtube.com/watch?v=dQw4w9WgXcQ
4512
+ attributionEnabled:
4513
+ type: boolean
4514
+ default: true
4515
+ description: |
4516
+ When false, the landing page skips Spotify login and only tracks
4517
+ the landing-page click. Omit or send true to keep attribution.
4518
+ Sending false requires the organization to be allowed to turn
4519
+ attribution off, and cannot be combined with `autoFollow: true`.
3562
4520
 
3563
4521
  SoundlinkDetail:
3564
4522
  allOf:
@@ -3571,6 +4529,7 @@ components:
3571
4529
  - tiktokPixelId
3572
4530
  - appleMusicUrl
3573
4531
  - youtubeMusicUrl
4532
+ - attributionEnabled
3574
4533
  properties:
3575
4534
  autoFollow:
3576
4535
  type: boolean
@@ -3604,6 +4563,11 @@ components:
3604
4563
  YouTube Music URL stored on this soundlink. `null` if not set.
3605
4564
  Input hosts such as `youtu.be` are returned as the canonical
3606
4565
  `music.youtube.com` song or playlist URL.
4566
+ attributionEnabled:
4567
+ type: boolean
4568
+ description: |
4569
+ Whether this soundlink keeps Spotify attribution. `false`
4570
+ means the landing page skips login and only tracks the click.
3607
4571
 
3608
4572
  SoundlinkDetailResponse:
3609
4573
  type: object
@@ -3995,6 +4959,188 @@ components:
3995
4959
  type: number
3996
4960
  description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
3997
4961
 
4962
+ SoundlinkCohortRetentionResponse:
4963
+ type: object
4964
+ required: [data, meta]
4965
+ properties:
4966
+ data:
4967
+ type: object
4968
+ required: [schemaVersion, items]
4969
+ properties:
4970
+ schemaVersion:
4971
+ type: string
4972
+ description: Version of the `soundlink_cohort_retention_daily` row schema. Pin your ingest pipeline to this.
4973
+ example: '1.0'
4974
+ items:
4975
+ type: array
4976
+ items:
4977
+ $ref: '#/components/schemas/SoundlinkCohortRetentionDailyRow'
4978
+ meta:
4979
+ $ref: '#/components/schemas/Meta'
4980
+
4981
+ SoundlinkCohortRetentionDailyRow:
4982
+ type: object
4983
+ description: |
4984
+ One row of the `soundlink_cohort_retention_daily` v1.0 schema.
4985
+ Primary key: `(provider, account_id, cohort_date, soundlink_id)`.
4986
+ Rows are idempotent. Re-ingesting on the primary key is safe.
4987
+ A day-N value is final once day N has passed for the cohort date.
4988
+ Until then it is `null`.
4989
+ required:
4990
+ - provider
4991
+ - account_id
4992
+ - schema_version
4993
+ - cohort_date
4994
+ - cohort_date_timezone
4995
+ - exported_at
4996
+ - soundlink_id
4997
+ - soundlink_name
4998
+ - soundlink_target_type
4999
+ - cohort_size
5000
+ - returned_on_day_1
5001
+ - retention_by_day_1
5002
+ - returned_on_day_2
5003
+ - retention_by_day_2
5004
+ - returned_on_day_3
5005
+ - retention_by_day_3
5006
+ - returned_on_day_4
5007
+ - retention_by_day_4
5008
+ - returned_on_day_5
5009
+ - retention_by_day_5
5010
+ - returned_on_day_6
5011
+ - retention_by_day_6
5012
+ - returned_on_day_7
5013
+ - retention_by_day_7
5014
+ properties:
5015
+ provider:
5016
+ type: string
5017
+ enum: [soundlink]
5018
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
5019
+ account_id:
5020
+ type: string
5021
+ description: Soundlink organization ID (UUID).
5022
+ schema_version:
5023
+ type: string
5024
+ description: Schema version string. Pin your ingest pipeline to this value.
5025
+ example: '1.0'
5026
+ cohort_date:
5027
+ type: string
5028
+ format: date
5029
+ description: UTC calendar date (`YYYY-MM-DD`) on which this cohort's listeners first played via the soundlink.
5030
+ cohort_date_timezone:
5031
+ type: string
5032
+ enum: [UTC]
5033
+ description: Always `UTC`.
5034
+ exported_at:
5035
+ type: string
5036
+ format: date-time
5037
+ description: ISO 8601 UTC timestamp when this row was generated.
5038
+ soundlink_id:
5039
+ type: string
5040
+ description: Unique ID of this soundlink.
5041
+ example: V1StGXR8_Z5jdHi6B-myT
5042
+ soundlink_name:
5043
+ type: string
5044
+ description: Human-readable soundlink name.
5045
+ soundlink_target_type:
5046
+ type: string
5047
+ nullable: true
5048
+ enum: [track, playlist]
5049
+ description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
5050
+ soundlink_target_isrc:
5051
+ type: string
5052
+ nullable: true
5053
+ description: ISRC of the promoted track. Currently always `null`.
5054
+ soundlink_target_spotify_track_id:
5055
+ type: string
5056
+ nullable: true
5057
+ description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
5058
+ soundlink_target_playlist_id:
5059
+ type: string
5060
+ nullable: true
5061
+ description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
5062
+ cohort_size:
5063
+ type: integer
5064
+ minimum: 0
5065
+ description: Unique listeners whose first play via this soundlink was on `cohort_date`.
5066
+ returned_on_day_1:
5067
+ type: integer
5068
+ nullable: true
5069
+ minimum: 0
5070
+ description: Cohort listeners who played again on exactly day 1 after their first play. `null` until day 1 has passed.
5071
+ retention_by_day_1:
5072
+ type: number
5073
+ nullable: true
5074
+ minimum: 0
5075
+ maximum: 1
5076
+ description: Share of `cohort_size` who played again on any day from 1 to 1 (end-day, cumulative), rounded to 4 decimals. `null` until day 1 has passed.
5077
+ returned_on_day_2:
5078
+ type: integer
5079
+ nullable: true
5080
+ minimum: 0
5081
+ description: Cohort listeners who played again on exactly day 2 after their first play. `null` until day 2 has passed.
5082
+ retention_by_day_2:
5083
+ type: number
5084
+ nullable: true
5085
+ minimum: 0
5086
+ maximum: 1
5087
+ description: Share of `cohort_size` who played again on any day from 1 to 2 (end-day, cumulative), rounded to 4 decimals. `null` until day 2 has passed.
5088
+ returned_on_day_3:
5089
+ type: integer
5090
+ nullable: true
5091
+ minimum: 0
5092
+ description: Cohort listeners who played again on exactly day 3 after their first play. `null` until day 3 has passed.
5093
+ retention_by_day_3:
5094
+ type: number
5095
+ nullable: true
5096
+ minimum: 0
5097
+ maximum: 1
5098
+ description: Share of `cohort_size` who played again on any day from 1 to 3 (end-day, cumulative), rounded to 4 decimals. `null` until day 3 has passed.
5099
+ returned_on_day_4:
5100
+ type: integer
5101
+ nullable: true
5102
+ minimum: 0
5103
+ description: Cohort listeners who played again on exactly day 4 after their first play. `null` until day 4 has passed.
5104
+ retention_by_day_4:
5105
+ type: number
5106
+ nullable: true
5107
+ minimum: 0
5108
+ maximum: 1
5109
+ description: Share of `cohort_size` who played again on any day from 1 to 4 (end-day, cumulative), rounded to 4 decimals. `null` until day 4 has passed.
5110
+ returned_on_day_5:
5111
+ type: integer
5112
+ nullable: true
5113
+ minimum: 0
5114
+ description: Cohort listeners who played again on exactly day 5 after their first play. `null` until day 5 has passed.
5115
+ retention_by_day_5:
5116
+ type: number
5117
+ nullable: true
5118
+ minimum: 0
5119
+ maximum: 1
5120
+ description: Share of `cohort_size` who played again on any day from 1 to 5 (end-day, cumulative), rounded to 4 decimals. `null` until day 5 has passed.
5121
+ returned_on_day_6:
5122
+ type: integer
5123
+ nullable: true
5124
+ minimum: 0
5125
+ description: Cohort listeners who played again on exactly day 6 after their first play. `null` until day 6 has passed.
5126
+ retention_by_day_6:
5127
+ type: number
5128
+ nullable: true
5129
+ minimum: 0
5130
+ maximum: 1
5131
+ description: Share of `cohort_size` who played again on any day from 1 to 6 (end-day, cumulative), rounded to 4 decimals. `null` until day 6 has passed.
5132
+ returned_on_day_7:
5133
+ type: integer
5134
+ nullable: true
5135
+ minimum: 0
5136
+ description: Cohort listeners who played again on exactly day 7 after their first play. `null` until day 7 has passed.
5137
+ retention_by_day_7:
5138
+ type: number
5139
+ nullable: true
5140
+ minimum: 0
5141
+ maximum: 1
5142
+ description: Share of `cohort_size` who played again on any day from 1 to 7 (end-day, cumulative), rounded to 4 decimals. `null` until day 7 has passed.
5143
+
3998
5144
  # --- Videos ---
3999
5145
 
4000
5146
  VideoImportRequest:
@@ -4231,6 +5377,31 @@ components:
4231
5377
  meta:
4232
5378
  requestId: 550e8400-e29b-41d4-a716-446655440000
4233
5379
 
5380
+ PremiumAnalyticsForbidden:
5381
+ description: |
5382
+ Authenticated with a valid scope, but the organization's subscription
5383
+ is not on a Label, Enterprise, committed, or self-serve plan.
5384
+ Applies to listening insights and cohort retention endpoints.
5385
+ content:
5386
+ application/json:
5387
+ schema:
5388
+ $ref: '#/components/schemas/ErrorResponse'
5389
+ examples:
5390
+ premium_plan_required:
5391
+ value:
5392
+ error:
5393
+ code: premium_plan_required
5394
+ message: 'Listening insights and cohort retention require a Label, Enterprise, committed, or self-serve plan.'
5395
+ meta:
5396
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5397
+ insufficient_scope:
5398
+ value:
5399
+ error:
5400
+ code: insufficient_scope
5401
+ message: 'This token does not have the metrics:read scope.'
5402
+ meta:
5403
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5404
+
4234
5405
  CreateCampaignForbidden:
4235
5406
  description: |
4236
5407
  Valid key but missing the `campaigns:write` scope, or the calling
@@ -4288,7 +5459,9 @@ components:
4288
5459
 
4289
5460
  CreateSoundlinkForbidden:
4290
5461
  description: |
4291
- Valid credentials but missing the `soundlinks:write` scope.
5462
+ Valid credentials but missing the `soundlinks:write` scope, the
5463
+ organization has no self-serve plan, or the organization is not allowed
5464
+ to create a soundlink with attribution off.
4292
5465
  content:
4293
5466
  application/json:
4294
5467
  schema:
@@ -4301,6 +5474,20 @@ components:
4301
5474
  message: 'This key does not have the soundlinks:write scope.'
4302
5475
  meta:
4303
5476
  requestId: 550e8400-e29b-41d4-a716-446655440000
5477
+ soundlink_plan_required:
5478
+ value:
5479
+ error:
5480
+ code: soundlink_plan_required
5481
+ message: 'Creating a Soundlink requires a self-serve plan.'
5482
+ meta:
5483
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5484
+ attribution_not_enabled:
5485
+ value:
5486
+ error:
5487
+ code: attribution_not_enabled
5488
+ message: 'This organization cannot create a soundlink with attribution off.'
5489
+ meta:
5490
+ requestId: 550e8400-e29b-41d4-a716-446655440000
4304
5491
  CreateSoundlinkUnprocessable:
4305
5492
  description: Request body is well-formed but the Spotify URL is invalid.
4306
5493
  content:
@@ -4317,6 +5504,86 @@ components:
4317
5504
  meta:
4318
5505
  requestId: 550e8400-e29b-41d4-a716-446655440000
4319
5506
 
5507
+ PixelForbidden:
5508
+ description: |
5509
+ Valid credentials but missing the required scope, or custom pixels
5510
+ are not enabled for the organization.
5511
+ content:
5512
+ application/json:
5513
+ schema:
5514
+ $ref: '#/components/schemas/ErrorResponse'
5515
+ examples:
5516
+ insufficient_scope:
5517
+ value:
5518
+ error:
5519
+ code: insufficient_scope
5520
+ message: 'This key does not have the campaigns:write scope.'
5521
+ meta:
5522
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5523
+ custom_pixel_not_enabled:
5524
+ value:
5525
+ error:
5526
+ code: custom_pixel_not_enabled
5527
+ message: 'This organization does not have a custom Meta pixel enabled.'
5528
+ meta:
5529
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5530
+
5531
+ UpdatePixelBadRequest:
5532
+ description: |
5533
+ Missing or malformed request body, unsupported platform, or the
5534
+ access token is already used with another pixel.
5535
+ content:
5536
+ application/json:
5537
+ schema:
5538
+ $ref: '#/components/schemas/ErrorResponse'
5539
+ examples:
5540
+ invalid_body:
5541
+ value:
5542
+ error:
5543
+ code: invalid_request
5544
+ message: 'Invalid request body at accessToken: Required.'
5545
+ meta:
5546
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5547
+ access_token_in_use:
5548
+ value:
5549
+ error:
5550
+ code: invalid_request
5551
+ message: 'Access token is already in use with another pixel ID'
5552
+ meta:
5553
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5554
+
5555
+ PixelConflict:
5556
+ description: |
5557
+ The pixel is configured by another organization.
5558
+ content:
5559
+ application/json:
5560
+ schema:
5561
+ $ref: '#/components/schemas/ErrorResponse'
5562
+ examples:
5563
+ pixel_owned_by_another_organization:
5564
+ value:
5565
+ error:
5566
+ code: meta_pixel_conflict
5567
+ message: "This pixel can't be used with this account. Check the pixel ID and access token, or contact support."
5568
+ meta:
5569
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5570
+
5571
+ PixelTestEventBadRequest:
5572
+ description: |
5573
+ Meta rejected the event because the pixel id or access token is wrong.
5574
+ content:
5575
+ application/json:
5576
+ schema:
5577
+ $ref: '#/components/schemas/ErrorResponse'
5578
+ examples:
5579
+ meta_rejected:
5580
+ value:
5581
+ error:
5582
+ code: invalid_request
5583
+ message: 'Meta rejected the test event for pixel 1234567890123456. Check the pixel id and access token.'
5584
+ meta:
5585
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5586
+
4320
5587
  InsufficientCredit:
4321
5588
  description: Wallet balance is too low to cover `dailyBudget * durationDays`
4322
5589
  content:
@@ -4415,18 +5682,20 @@ components:
4415
5682
  meta:
4416
5683
  requestId: 550e8400-e29b-41d4-a716-446655440000
4417
5684
 
4418
- TierUpdateCooldown:
5685
+ LearningEditAckRequired:
4419
5686
  description: |
4420
- Campaign tiers were updated in the last 72 hours. Wait for the cooldown
4421
- to end before updating again.
5687
+ Ad sets for one or more active tiers are still learning. Send the same
5688
+ request with `acknowledgeLearningWarning: true` to continue.
4422
5689
  content:
4423
5690
  application/json:
4424
5691
  schema:
4425
5692
  $ref: '#/components/schemas/ErrorResponse'
4426
5693
  example:
4427
5694
  error:
4428
- code: tier_update_cooldown
4429
- message: 'Campaign tiers were updated in the last 72 hours. Wait for the cooldown to end before updating again.'
5695
+ code: learning_edit_ack_required
5696
+ message: 'Ad sets are still learning. Acknowledge the warning to continue.'
5697
+ details:
5698
+ tierIds: [1, 2]
4430
5699
  meta:
4431
5700
  requestId: 550e8400-e29b-41d4-a716-446655440000
4432
5701