soundlink 2.3.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,15 @@ 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
- | Soundlink reads (list, detail, metrics overview/timeseries/breakdown/engagement, JSONL exports) | `soundlinks:read` | API key (Bearer) or OAuth Bearer |
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 |
47
+ | Soundlink writes (create, archive, test events) | `soundlinks:write` | API key (Bearer) or OAuth Bearer |
48
+ | Wallet read (`GET /v1/wallet`) | `wallet:read` | API key (Bearer) or OAuth Bearer |
43
49
 
44
50
  Per-operation scope requirements are also marked with `x-required-scope`
45
51
  (except `GET /v1/ping`, which accepts any valid credential with at least
@@ -63,6 +69,10 @@ security:
63
69
  tags:
64
70
  - name: System
65
71
  description: Connectivity and auth verification
72
+ - name: Wallet
73
+ description: Organization wallet balance
74
+ - name: Pixels
75
+ description: Organization ad pixels that receive a copy of Soundlink conversion events
66
76
  - name: Campaigns
67
77
  description: Campaign listing, detail, creation, and wallet management (budget, stop, tiers)
68
78
  - name: Metrics
@@ -70,7 +80,7 @@ tags:
70
80
  - name: Videos
71
81
  description: Partner video library import for Full Control campaigns
72
82
  - name: Soundlinks
73
- description: Soundlink listing, detail, and performance metrics
83
+ description: Soundlink listing, detail, creation, archive, and performance metrics
74
84
 
75
85
  paths:
76
86
  /v1/ping:
@@ -113,6 +123,203 @@ paths:
113
123
  '429': { $ref: '#/components/responses/RateLimited' }
114
124
  '500': { $ref: '#/components/responses/InternalError' }
115
125
 
126
+ /v1/wallet:
127
+ get:
128
+ operationId: getWallet
129
+ summary: Get organization wallet balance
130
+ description: |
131
+ Returns the organization wallet on the API key. Requires `wallet:read`.
132
+ Existing keys do not have this scope until it is granted.
133
+
134
+ `available` is the amount `POST /v1/campaigns` checks before reserving.
135
+ When create returns `402 insufficient_credit`, `error.details.available`
136
+ matches this field. `reserved` is the sum of active reservations.
137
+
138
+ An organization with no credits row returns zeros and `updatedAt: null`.
139
+ tags: [Wallet]
140
+ x-required-scope: wallet:read
141
+ security:
142
+ - apiKeyBearerAuth: []
143
+ - oauthBearer: []
144
+ responses:
145
+ '200':
146
+ description: Wallet snapshot
147
+ content:
148
+ application/json:
149
+ schema:
150
+ $ref: '#/components/schemas/GetWalletResponse'
151
+ example:
152
+ data:
153
+ balance: 500
154
+ available: 350
155
+ reserved: 150
156
+ currency: USD
157
+ updatedAt: '2026-04-01T10:00:00Z'
158
+ meta:
159
+ requestId: 550e8400-e29b-41d4-a716-446655440000
160
+ '401': { $ref: '#/components/responses/Unauthorized' }
161
+ '403': { $ref: '#/components/responses/Forbidden' }
162
+ '429': { $ref: '#/components/responses/RateLimited' }
163
+ '500': { $ref: '#/components/responses/InternalError' }
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
+
116
323
  /v1/strategies:
117
324
  get:
118
325
  operationId: listStrategies
@@ -194,6 +401,12 @@ paths:
194
401
  dailyBudget: 20.0
195
402
  totalBudget: 140.0
196
403
  campaignDuration: 7
404
+ artistId: 4gzpq5DPGxSnKTe4SA8HAU
405
+ artistName: Coldplay
406
+ trackId: 3AJwUDP919kvQ9QcozQPxg
407
+ playlistId: null
408
+ trackName: Yellow
409
+ campaignUrl: https://getsoundlink.com/orgs/org_xyz/insights/V1StGXR8_Z5jdHi6B-myT
197
410
  createdAt: '2026-04-01T10:00:00Z'
198
411
  updatedAt: '2026-04-08T12:00:00Z'
199
412
  pagination:
@@ -343,6 +556,12 @@ paths:
343
556
  totalBudget: 140.0
344
557
  campaignDuration: 7
345
558
  strategyType: custom
559
+ artistId: 4gzpq5DPGxSnKTe4SA8HAU
560
+ artistName: Coldplay
561
+ trackId: 3AJwUDP919kvQ9QcozQPxg
562
+ playlistId: null
563
+ trackName: Yellow
564
+ campaignUrl: https://getsoundlink.com/orgs/org_xyz/insights/V1StGXR8_Z5jdHi6B-myT
346
565
  createdAt: '2026-04-01T10:00:00Z'
347
566
  updatedAt: '2026-04-08T12:00:00Z'
348
567
  meta:
@@ -363,9 +582,17 @@ paths:
363
582
 
364
583
  **Wallet campaigns only** (`generation: 3`).
365
584
 
366
- Stopping is idempotent at the campaign level: a second stop on an
367
- already-stopped campaign succeeds without double-refunding. The
368
- `Idempotency-Key` header is also **required** so retries of the same
585
+ **Statuses that accept stop** and return `stopped`: `active`,
586
+ `inactive`, `restarting`, `restart_failed`, `renew_failed`, and
587
+ `renew_awaiting_charge`.
588
+
589
+ **Already terminal:** `stopped` and `ended` succeed without changing
590
+ status. The response `status` stays `stopped` or `ended`. A second
591
+ stop does not double-refund.
592
+
593
+ **Retry later (`400 invalid_request`):** `creating` and `renewing`.
594
+
595
+ The `Idempotency-Key` header is **required** so retries of the same
369
596
  request replay the original response without repeating side effects.
370
597
 
371
598
  **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
@@ -398,6 +625,56 @@ paths:
398
625
  '429': { $ref: '#/components/responses/RateLimited' }
399
626
  '500': { $ref: '#/components/responses/InternalError' }
400
627
 
628
+ /v1/campaigns/{campaignId}/auto-renew:
629
+ put:
630
+ operationId: updateCampaignAutoRenew
631
+ summary: Toggle wallet campaign auto-renew
632
+ description: |
633
+ Sets auto-renew for a wallet-funded campaign. Requires the
634
+ `campaigns:write` scope and an `Idempotency-Key` header.
635
+
636
+ **Wallet campaigns only** (`generation: 3`). Non-wallet campaigns
637
+ return `400`. Allowed when the campaign status is `active` or
638
+ `renew_failed`. A matching stored value is a no-op success.
639
+
640
+ **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
641
+ tags: [Campaigns]
642
+ x-required-scope: campaigns:write
643
+ security:
644
+ - apiKeyBearerAuth: []
645
+ - oauthBearer: []
646
+ parameters:
647
+ - $ref: '#/components/parameters/campaignId'
648
+ - $ref: '#/components/parameters/idempotencyKey'
649
+ requestBody:
650
+ required: true
651
+ content:
652
+ application/json:
653
+ schema:
654
+ $ref: '#/components/schemas/UpdateCampaignAutoRenewRequest'
655
+ example:
656
+ autoRenew: true
657
+ responses:
658
+ '200':
659
+ description: Auto-renew updated
660
+ content:
661
+ application/json:
662
+ schema:
663
+ $ref: '#/components/schemas/UpdateCampaignAutoRenewResponse'
664
+ example:
665
+ data:
666
+ campaignId: campaign-uuid
667
+ autoRenew: true
668
+ meta:
669
+ requestId: 550e8400-e29b-41d4-a716-446655440000
670
+ '400': { $ref: '#/components/responses/BadRequest' }
671
+ '401': { $ref: '#/components/responses/Unauthorized' }
672
+ '403': { $ref: '#/components/responses/Forbidden' }
673
+ '404': { $ref: '#/components/responses/NotFound' }
674
+ '409': { $ref: '#/components/responses/IdempotencyKeyConflict' }
675
+ '429': { $ref: '#/components/responses/RateLimited' }
676
+ '500': { $ref: '#/components/responses/InternalError' }
677
+
401
678
  /v1/campaigns/{campaignId}/budget/increase:
402
679
  post:
403
680
  operationId: increaseCampaignBudget
@@ -487,8 +764,10 @@ paths:
487
764
  is applied asynchronously after acceptance (`accepted: true`).
488
765
 
489
766
  Domain rules (also returned as `invalid_request` when violated):
490
- - `targetDailyBudget` must be at least `$10`/day and lower than the
491
- current daily budget
767
+ - `targetDailyBudget` must be at least the campaign's enabled-ad-set
768
+ minimum gross (`minLowerDailyBudgetGrossCurrent`, or the max of
769
+ current and next when `mode` is `current_and_renewals`) and lower
770
+ than the current daily budget
492
771
  - more than 3 days must remain in the current cycle
493
772
 
494
773
  **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
@@ -539,8 +818,9 @@ paths:
539
818
  summary: Get campaign tier allocation
540
819
  description: |
541
820
  Returns the current geographic tier allocation for a wallet campaign:
542
- which tiers are enabled, their budget share, and when tiers were last
543
- 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.
544
824
 
545
825
  **Wallet campaigns only** (`generation: 3`).
546
826
 
@@ -567,10 +847,12 @@ paths:
567
847
  tierName: US
568
848
  isEnabled: true
569
849
  allocationPercent: 60
850
+ learningStatus: LEARNING
570
851
  - tierId: 2
571
852
  tierName: UK
572
853
  isEnabled: false
573
854
  allocationPercent: 40
855
+ learningStatus: null
574
856
  meta:
575
857
  requestId: 550e8400-e29b-41d4-a716-446655440000
576
858
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -594,8 +876,13 @@ paths:
594
876
  - `newAllocationPercent` values must sum to **100**
595
877
  - At least one tier must have `isEnabled: true`
596
878
 
597
- **Cooldown:** after a successful update, further tier changes are
598
- 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.
599
886
 
600
887
  **Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
601
888
  tags: [Campaigns]
@@ -619,6 +906,7 @@ paths:
619
906
  - targetingTierId: 2
620
907
  isEnabled: true
621
908
  newAllocationPercent: 30
909
+ acknowledgeLearningWarning: true
622
910
  responses:
623
911
  '200':
624
912
  description: Updated tier allocation
@@ -650,7 +938,83 @@ paths:
650
938
  '401': { $ref: '#/components/responses/Unauthorized' }
651
939
  '403': { $ref: '#/components/responses/Forbidden' }
652
940
  '404': { $ref: '#/components/responses/NotFound' }
653
- '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' }
654
1018
  '429': { $ref: '#/components/responses/RateLimited' }
655
1019
  '500': { $ref: '#/components/responses/InternalError' }
656
1020
 
@@ -659,8 +1023,9 @@ paths:
659
1023
  operationId: getCampaignMetricsOverview
660
1024
  summary: Campaign metrics overview
661
1025
  description: |
662
- Campaign-level totals for a date range: spend, conversions, listeners,
663
- 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
664
1029
  `/metrics/breakdown` for those.
665
1030
 
666
1031
  Suitable for dashboards and quick syncs.
@@ -685,6 +1050,7 @@ paths:
685
1050
  example:
686
1051
  data:
687
1052
  listeners: 4821
1053
+ total_listeners: 5100
688
1054
  streams: 9340
689
1055
  followers: 312
690
1056
  impressions: 48210
@@ -696,7 +1062,159 @@ paths:
696
1062
  currency: USD
697
1063
  cpl: 0.028
698
1064
  cpf: 0.43
699
- streams_per_listener: 1.94
1065
+ streams_per_listener: 1.83
1066
+ meta:
1067
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1068
+ '400': { $ref: '#/components/responses/BadRequest' }
1069
+ '401': { $ref: '#/components/responses/Unauthorized' }
1070
+ '403': { $ref: '#/components/responses/Forbidden' }
1071
+ '404': { $ref: '#/components/responses/NotFound' }
1072
+ '429': { $ref: '#/components/responses/RateLimited' }
1073
+ '500': { $ref: '#/components/responses/InternalError' }
1074
+
1075
+ /v1/campaigns/{campaignId}/metrics/creatives:
1076
+ get:
1077
+ operationId: getCampaignCreativeMetrics
1078
+ summary: Campaign creative metrics
1079
+ description: |
1080
+ Lifetime creative performance for one campaign, grouped by background
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.
1086
+
1087
+ Spend is omitted until media spend and fees can be split. Ratios use
1088
+ the same lifetime basis as the Creatives tab.
1089
+
1090
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
1091
+ tags: [Metrics]
1092
+ security:
1093
+ - apiKeyBearerAuth: []
1094
+ - oauthBearer: []
1095
+ x-required-scope: metrics:read
1096
+ parameters:
1097
+ - $ref: '#/components/parameters/campaignId'
1098
+ responses:
1099
+ '200':
1100
+ description: Creative groups for the campaign
1101
+ content:
1102
+ application/json:
1103
+ schema:
1104
+ $ref: '#/components/schemas/CreativeMetricsResponse'
1105
+ example:
1106
+ data:
1107
+ creatives:
1108
+ - video_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
1109
+ caption: Late night version
1110
+ listeners: 400
1111
+ followers: 80
1112
+ link_clicks: 280
1113
+ cpl: 0.25
1114
+ cpf: 1.25
1115
+ cpc_linkclick: 0.357
1116
+ frequency: 1.8
1117
+ children:
1118
+ - caption: Late night version
1119
+ language: en
1120
+ spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1121
+ timestamp_start_ms: 45000
1122
+ timestamp_end_ms: 60000
1123
+ listeners: 200
1124
+ followers: 40
1125
+ link_clicks: 120
1126
+ cpl: 0.3
1127
+ cpf: 1.5
1128
+ cpc_linkclick: 0.5
1129
+ frequency: 2
1130
+ - caption: Daytime version
1131
+ language: en
1132
+ spotify_track_id: 11dFghVXANMlKmJXsNCbNl
1133
+ timestamp_start_ms: 0
1134
+ timestamp_end_ms: 15000
1135
+ listeners: 200
1136
+ followers: 40
1137
+ link_clicks: 160
1138
+ cpl: 0.2
1139
+ cpf: 1
1140
+ cpc_linkclick: 0.25
1141
+ frequency: 1.5
1142
+ meta:
1143
+ requestId: 550e8400-e29b-41d4-a716-446655440000
1144
+ '400': { $ref: '#/components/responses/BadRequest' }
1145
+ '401': { $ref: '#/components/responses/Unauthorized' }
1146
+ '403': { $ref: '#/components/responses/Forbidden' }
1147
+ '404': { $ref: '#/components/responses/NotFound' }
1148
+ '429': { $ref: '#/components/responses/RateLimited' }
1149
+ '500': { $ref: '#/components/responses/InternalError' }
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
700
1218
  meta:
701
1219
  requestId: 550e8400-e29b-41d4-a716-446655440000
702
1220
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -748,18 +1266,18 @@ paths:
748
1266
  - $ref: '#/components/parameters/sortOrder'
749
1267
  responses:
750
1268
  '200':
751
- description: Paginated per-day country rows (`campaign_country_daily` schema)
1269
+ description: Paginated per-day country rows (`campaign_country_daily` schema v1.1)
752
1270
  content:
753
1271
  application/json:
754
1272
  schema:
755
1273
  $ref: '#/components/schemas/MetricsBreakdownResponse'
756
1274
  example:
757
1275
  data:
758
- schemaVersion: '1.0'
1276
+ schemaVersion: '1.1'
759
1277
  items:
760
1278
  - provider: soundlink
761
1279
  account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
762
- schema_version: '1.0'
1280
+ schema_version: '1.1'
763
1281
  report_date: '2026-04-01'
764
1282
  report_date_timezone: UTC
765
1283
  exported_at: '2026-05-20T03:00:00Z'
@@ -775,8 +1293,11 @@ paths:
775
1293
  link_clicks: 89
776
1294
  streams: 203
777
1295
  listeners: 145
1296
+ new_listeners: 145
1297
+ returning_listeners: 40
1298
+ total_listeners: 185
778
1299
  followers: 12
779
- streams_per_listener: 1.4
1300
+ streams_per_listener: 1.1
780
1301
  spend_media: 42.50
781
1302
  spend_total: 53.13
782
1303
  fees: 10.63
@@ -864,8 +1385,8 @@ paths:
864
1385
  schema:
865
1386
  $ref: '#/components/schemas/BreakdownRow'
866
1387
  example: |
867
- {"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"}
868
- {"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"}
869
1390
  '400': { $ref: '#/components/responses/BadRequest' }
870
1391
  '401': { $ref: '#/components/responses/Unauthorized' }
871
1392
  '403': { $ref: '#/components/responses/Forbidden' }
@@ -1064,14 +1585,130 @@ paths:
1064
1585
  '429': { $ref: '#/components/responses/RateLimited' }
1065
1586
  '500': { $ref: '#/components/responses/InternalError' }
1066
1587
 
1067
- /v1/soundlinks:
1588
+ /v1/campaigns/{campaignId}/metrics/retention:
1068
1589
  get:
1069
- operationId: listSoundlinks
1070
- summary: List soundlinks
1590
+ operationId: getCampaignRetention
1591
+ summary: Campaign cohort retention
1071
1592
  description: |
1072
- Returns the organization's self-serve soundlinks. Soundlinks linked
1073
- to a campaign are the campaign's underlying resource and are served
1074
- by the Campaigns endpoints instead.
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
+
1704
+ /v1/soundlinks:
1705
+ get:
1706
+ operationId: listSoundlinks
1707
+ summary: List soundlinks
1708
+ description: |
1709
+ Returns the organization's self-serve soundlinks. Soundlinks linked
1710
+ to a campaign are the campaign's underlying resource and are served
1711
+ by the Campaigns endpoints instead.
1075
1712
 
1076
1713
  Soundlink schemas contain no financial fields: ads for self-serve
1077
1714
  soundlinks run in your own Meta account, so spend is not visible to
@@ -1131,7 +1768,8 @@ paths:
1131
1768
  API equivalent of the in-app create flow. It does not create a wallet
1132
1769
  campaign and does not appear on `GET /v1/campaigns`.
1133
1770
 
1134
- 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`.
1135
1773
 
1136
1774
  `Idempotency-Key` is **required**. Reusing the key with an unchanged
1137
1775
  body replays the original `201`; a different body returns
@@ -1159,6 +1797,7 @@ paths:
1159
1797
  spotifyUrl: 'https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl'
1160
1798
  autoFollow: true
1161
1799
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1800
+ attributionEnabled: true
1162
1801
  metaPixelId: '1234567890123456'
1163
1802
  metaConversionAccessToken: 'EAAB...'
1164
1803
  playlist:
@@ -1185,8 +1824,11 @@ paths:
1185
1824
  createdAt: '2026-04-01T10:00:00Z'
1186
1825
  autoFollow: true
1187
1826
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1827
+ attributionEnabled: true
1188
1828
  metaPixelId: '1234567890123456'
1189
1829
  tiktokPixelId: null
1830
+ appleMusicUrl: null
1831
+ youtubeMusicUrl: null
1190
1832
  meta:
1191
1833
  requestId: 550e8400-e29b-41d4-a716-446655440000
1192
1834
  '400': { $ref: '#/components/responses/CreateSoundlinkBadRequest' }
@@ -1232,8 +1874,11 @@ paths:
1232
1874
  createdAt: '2026-04-01T10:00:00Z'
1233
1875
  autoFollow: true
1234
1876
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1877
+ attributionEnabled: true
1235
1878
  metaPixelId: '1234567890123456'
1236
1879
  tiktokPixelId: null
1880
+ appleMusicUrl: null
1881
+ youtubeMusicUrl: null
1237
1882
  meta:
1238
1883
  requestId: 550e8400-e29b-41d4-a716-446655440000
1239
1884
  '401': { $ref: '#/components/responses/Unauthorized' }
@@ -1241,15 +1886,13 @@ paths:
1241
1886
  '404': { $ref: '#/components/responses/NotFound' }
1242
1887
  '429': { $ref: '#/components/responses/RateLimited' }
1243
1888
  '500': { $ref: '#/components/responses/InternalError' }
1244
-
1245
1889
  delete:
1246
1890
  operationId: archiveSoundlink
1247
1891
  summary: Archive a soundlink
1248
1892
  description: |
1249
1893
  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.
1894
+ in the app: the public page stops resolving, and this cannot be undone
1895
+ via the Public API.
1253
1896
 
1254
1897
  Requires `soundlinks:write`. Campaign-linked soundlinks, soundlinks
1255
1898
  that are not `active`, and ids that do not belong to the org return
@@ -1280,8 +1923,11 @@ paths:
1280
1923
  createdAt: '2026-04-01T10:00:00Z'
1281
1924
  autoFollow: true
1282
1925
  artistIdFollow: '4gzpq5DPGxSnKTe4SA8HAU'
1926
+ attributionEnabled: true
1283
1927
  metaPixelId: '1234567890123456'
1284
1928
  tiktokPixelId: null
1929
+ appleMusicUrl: null
1930
+ youtubeMusicUrl: null
1285
1931
  meta:
1286
1932
  requestId: 550e8400-e29b-41d4-a716-446655440000
1287
1933
  '401': { $ref: '#/components/responses/Unauthorized' }
@@ -1290,45 +1936,45 @@ paths:
1290
1936
  '429': { $ref: '#/components/responses/RateLimited' }
1291
1937
  '500': { $ref: '#/components/responses/InternalError' }
1292
1938
 
1293
- /v1/soundlinks/{soundlinkId}/metrics/overview:
1294
- get:
1295
- operationId: getSoundlinkMetricsOverview
1296
- summary: Soundlink metrics overview
1939
+ /v1/soundlinks/{soundlinkId}/test-events:
1940
+ post:
1941
+ operationId: sendSoundlinkTestEvents
1942
+ summary: Send a test conversion event for a soundlink
1297
1943
  description: |
1298
- Soundlink-level totals for a date range: landing page views, outbound
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).
1944
+ Sends the same test conversion event as the in-app "send test event"
1945
+ action. Pixels and tokens are read from the soundlink. This request
1946
+ has no body.
1305
1947
 
1306
- Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1948
+ When the soundlink has a Meta pixel, a live Meta Conversions API event
1949
+ named `Soundlink Stream` is sent to that pixel. When it has a TikTok
1950
+ pixel, a live TikTok `ViewContent` event is sent as well. These are
1951
+ not sandbox events: they appear in the ad platform's events manager.
1952
+
1953
+ Requires `soundlinks:write`. Unknown ids, another organization's
1954
+ soundlink, and campaign-linked soundlinks return `404`. Archived
1955
+ self-serve soundlinks are allowed. A soundlink with neither pixel
1956
+ returns `400`. Does not require `Idempotency-Key`; each call sends a
1957
+ new event.
1958
+
1959
+ **Auth:** Accepts API key or OAuth Bearer (`soundlinks:write`).
1307
1960
  tags: [Soundlinks]
1308
1961
  security:
1309
1962
  - apiKeyBearerAuth: []
1310
1963
  - oauthBearer: []
1311
- x-required-scope: soundlinks:read
1964
+ x-required-scope: soundlinks:write
1312
1965
  parameters:
1313
1966
  - $ref: '#/components/parameters/soundlinkId'
1314
- - $ref: '#/components/parameters/soundlinkStartDate'
1315
- - $ref: '#/components/parameters/soundlinkEndDate'
1316
1967
  responses:
1317
1968
  '200':
1318
- description: Soundlink totals
1969
+ description: Test event sent
1319
1970
  content:
1320
1971
  application/json:
1321
1972
  schema:
1322
- $ref: '#/components/schemas/SoundlinkMetricsOverviewResponse'
1973
+ $ref: '#/components/schemas/SendTestEventResponse'
1323
1974
  example:
1324
1975
  data:
1325
- views: 4821
1326
- link_clicks: 890
1327
- streams: 9340
1328
- listeners: 3980
1329
- followers: 312
1330
- streams_per_listener: 2.35
1331
- ctr_lp: 0.185
1976
+ soundlinkId: V1StGXR8_Z5jdHi6B-myT
1977
+ status: sent
1332
1978
  meta:
1333
1979
  requestId: 550e8400-e29b-41d4-a716-446655440000
1334
1980
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -1338,27 +1984,17 @@ paths:
1338
1984
  '429': { $ref: '#/components/responses/RateLimited' }
1339
1985
  '500': { $ref: '#/components/responses/InternalError' }
1340
1986
 
1341
- /v1/soundlinks/{soundlinkId}/metrics/timeseries:
1987
+ /v1/soundlinks/{soundlinkId}/metrics/overview:
1342
1988
  get:
1343
- operationId: getSoundlinkMetricsTimeseries
1344
- summary: Soundlink metrics timeseries
1989
+ operationId: getSoundlinkMetricsOverview
1990
+ summary: Soundlink metrics overview
1345
1991
  description: |
1346
- Per-day metrics for a soundlink. One row per `report_date`. Results
1347
- are paginated.
1348
-
1349
- **Row schema:** `soundlink_daily` v1.0. Rows are idempotent on the
1350
- primary key `(provider, account_id, report_date, soundlink_id)`;
1351
- re-ingesting is safe.
1352
-
1353
- **Mutability window:** rows for a given `report_date` can be revised
1354
- for up to 7 days after the date closes due to delayed Spotify playback
1355
- events. Re-fetch or re-ingest accordingly.
1356
-
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.
1992
+ Soundlink-level totals for a date range: landing page views, outbound
1993
+ clicks, listeners, streams, followers, and derived ratios. Totals are
1994
+ sums of country-day mart rows (`api_smart_link_country_daily`);
1995
+ `listeners` is the sum of daily country `new_listeners` (not
1996
+ period-unique). No per-day rows — use `/metrics/breakdown` for
1997
+ country-day rows (including new/returning splits).
1362
1998
 
1363
1999
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1364
2000
  tags: [Soundlinks]
@@ -1370,54 +2006,22 @@ paths:
1370
2006
  - $ref: '#/components/parameters/soundlinkId'
1371
2007
  - $ref: '#/components/parameters/soundlinkStartDate'
1372
2008
  - $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
2009
  responses:
1383
2010
  '200':
1384
- description: Paginated per-day rows (`soundlink_daily` schema)
2011
+ description: Soundlink totals
1385
2012
  content:
1386
2013
  application/json:
1387
2014
  schema:
1388
- $ref: '#/components/schemas/SoundlinkTimeseriesResponse'
2015
+ $ref: '#/components/schemas/SoundlinkMetricsOverviewResponse'
1389
2016
  example:
1390
2017
  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
2018
+ views: 4821
2019
+ link_clicks: 890
2020
+ streams: 9340
2021
+ listeners: 3980
2022
+ followers: 312
2023
+ streams_per_listener: 2.35
2024
+ ctr_lp: 0.185
1421
2025
  meta:
1422
2026
  requestId: 550e8400-e29b-41d4-a716-446655440000
1423
2027
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -1449,7 +2053,6 @@ paths:
1449
2053
  in your own Meta account, so spend is not visible to Soundlink.
1450
2054
 
1451
2055
  Maps to the **Countries** tab in the Soundlink Insights UI.
1452
- Use `/metrics/timeseries` for country-aggregated daily Trends rows.
1453
2056
 
1454
2057
  Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
1455
2058
  tags: [Soundlinks]
@@ -1781,13 +2384,128 @@ paths:
1781
2384
  '429': { $ref: '#/components/responses/RateLimited' }
1782
2385
  '500': { $ref: '#/components/responses/InternalError' }
1783
2386
 
2387
+ /v1/soundlinks/{soundlinkId}/metrics/retention:
2388
+ get:
2389
+ operationId: getSoundlinkRetention
2390
+ summary: Soundlink cohort retention
2391
+ description: |
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`.
2420
+
2421
+ Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
2422
+ tags: [Soundlinks]
2423
+ security:
2424
+ - apiKeyBearerAuth: []
2425
+ - oauthBearer: []
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
+
1784
2498
  /v1/videos/import:
1785
2499
  post:
1786
2500
  operationId: importVideo
1787
- summary: Import video(s) from public HTTPS MP4 URL(s)
2501
+ summary: Import video(s) from public HTTPS MP4 or QuickTime URL(s)
1788
2502
  description: |
1789
2503
  Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
1790
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.
1791
2509
 
1792
2510
  Requires the `videos:write` scope. Subject to a stricter per-credential rate
1793
2511
  limit than generic public API routes (default 20 imports per hour per API key
@@ -1818,7 +2536,7 @@ paths:
1818
2536
  value:
1819
2537
  videos:
1820
2538
  - url: 'https://cdn.example.com/a.mp4'
1821
- - url: 'https://cdn.example.com/b.mp4'
2539
+ - url: 'https://cdn.example.com/b.mov'
1822
2540
  responses:
1823
2541
  '200':
1824
2542
  description: Duplicate video already in the organization's library (sync legacy path only)
@@ -1903,6 +2621,18 @@ components:
1903
2621
  type: string
1904
2622
  description: Campaign identifier (UUID)
1905
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
+
1906
2636
  idempotencyKey:
1907
2637
  name: Idempotency-Key
1908
2638
  in: header
@@ -1913,7 +2643,7 @@ components:
1913
2643
  maxLength: 255
1914
2644
  description: |
1915
2645
  A unique string identifying this request, used to safely retry write
1916
- operations (create, stop, budget increase/decrease) without repeating
2646
+ operations (campaign create/stop/budget, soundlink create) without repeating
1917
2647
  side effects. Required on every request that references this parameter.
1918
2648
  Reusing this key with an unchanged request body replays the original
1919
2649
  response; reusing it with a different body returns
@@ -1963,7 +2693,11 @@ components:
1963
2693
  schema:
1964
2694
  type: string
1965
2695
  format: date
1966
- description: Inclusive start date (`YYYY-MM-DD`). Defaults to campaign start date.
2696
+ description: |
2697
+ Inclusive start date (`YYYY-MM-DD`). When omitted, the default depends
2698
+ on the endpoint: campaign overview and paginated breakdown use the
2699
+ campaign start date; engagement and JSONL export endpoints use the
2700
+ last 90 days ending today (see each operation).
1967
2701
 
1968
2702
  endDate:
1969
2703
  name: endDate
@@ -1989,7 +2723,7 @@ components:
1989
2723
  format: date
1990
2724
  description: |
1991
2725
  Inclusive start date (`YYYY-MM-DD`) for soundlink overview and
1992
- timeseries. Defaults to the soundlink creation date when omitted.
2726
+ breakdown. Defaults to the soundlink creation date when omitted.
1993
2727
 
1994
2728
  soundlinkEndDate:
1995
2729
  name: endDate
@@ -2011,47 +2745,290 @@ components:
2011
2745
  format: uuid
2012
2746
  description: Server-generated request ID. Include when contacting support.
2013
2747
 
2014
- Pagination:
2748
+ WalletData:
2015
2749
  type: object
2016
- required: [page, pageSize, totalCount, totalPages]
2750
+ required: [balance, available, reserved, currency, updatedAt]
2017
2751
  properties:
2018
- page:
2019
- type: integer
2020
- pageSize:
2021
- type: integer
2022
- totalCount:
2023
- type: integer
2024
- totalPages:
2025
- type: integer
2752
+ balance:
2753
+ type: number
2754
+ available:
2755
+ type: number
2756
+ reserved:
2757
+ type: number
2758
+ currency:
2759
+ type: string
2760
+ enum: [USD]
2761
+ updatedAt:
2762
+ type: string
2763
+ format: date-time
2764
+ nullable: true
2026
2765
 
2027
- Error:
2766
+ GetWalletResponse:
2028
2767
  type: object
2029
- required: [code, message]
2768
+ required: [data, meta]
2030
2769
  properties:
2031
- code:
2770
+ data:
2771
+ $ref: '#/components/schemas/WalletData'
2772
+ meta:
2773
+ $ref: '#/components/schemas/Meta'
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:
2032
2787
  type: string
2033
- description: Stable snake_case error code.
2034
- enum:
2035
- - invalid_api_key
2036
- - api_key_revoked
2037
- - api_key_expired
2038
- - insufficient_scope
2039
- - not_found
2040
- - campaign_not_found
2041
- - invalid_query_parameter
2042
- - invalid_date_range
2043
- - page_size_exceeded
2044
- - invalid_request
2045
- - invalid_genre
2046
- - invalid_duration_or_budget
2047
- - invalid_daily_budget
2048
- - invalid_duration_days
2049
- - invalid_spotify_url
2050
- - invalid_tier_budget_allocation
2051
- - invalid_tier_status
2052
- - tier_update_cooldown
2053
- - wallet_not_enabled
2054
- - insufficient_credit
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
+
2843
+ Pagination:
2844
+ type: object
2845
+ required: [page, pageSize, totalCount, totalPages]
2846
+ properties:
2847
+ page:
2848
+ type: integer
2849
+ pageSize:
2850
+ type: integer
2851
+ totalCount:
2852
+ type: integer
2853
+ totalPages:
2854
+ type: integer
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
+
2995
+ Error:
2996
+ type: object
2997
+ required: [code, message]
2998
+ properties:
2999
+ code:
3000
+ type: string
3001
+ description: Stable snake_case error code.
3002
+ enum:
3003
+ - invalid_api_key
3004
+ - invalid_token
3005
+ - api_key_revoked
3006
+ - api_key_expired
3007
+ - access_denied
3008
+ - insufficient_scope
3009
+ - not_found
3010
+ - not_in_listening_graph
3011
+ - campaign_not_found
3012
+ - invalid_query_parameter
3013
+ - invalid_date_range
3014
+ - page_size_exceeded
3015
+ - invalid_request
3016
+ - invalid_genre
3017
+ - invalid_duration_or_budget
3018
+ - invalid_daily_budget
3019
+ - invalid_duration_days
3020
+ - invalid_spotify_url
3021
+ - invalid_tier_budget_allocation
3022
+ - invalid_tier_status
3023
+ - learning_edit_ack_required
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
3031
+ - insufficient_credit
2055
3032
  - idempotency_key_conflict
2056
3033
  - rate_limit_exceeded
2057
3034
  - invalid_video_url
@@ -2083,7 +3060,19 @@ components:
2083
3060
 
2084
3061
  CampaignStatus:
2085
3062
  type: string
2086
- enum: [creating, active, paused, stopped, completed, failed, ended]
3063
+ enum:
3064
+ [
3065
+ creating,
3066
+ active,
3067
+ inactive,
3068
+ ended,
3069
+ renewing,
3070
+ restarting,
3071
+ restart_failed,
3072
+ renew_awaiting_charge,
3073
+ renew_failed,
3074
+ stopped,
3075
+ ]
2087
3076
 
2088
3077
  CampaignSummary:
2089
3078
  type: object
@@ -2097,6 +3086,12 @@ components:
2097
3086
  totalBudget,
2098
3087
  campaignDuration,
2099
3088
  generation,
3089
+ artistId,
3090
+ artistName,
3091
+ trackId,
3092
+ playlistId,
3093
+ trackName,
3094
+ campaignUrl,
2100
3095
  createdAt,
2101
3096
  updatedAt,
2102
3097
  ]
@@ -2127,6 +3122,48 @@ components:
2127
3122
  legacy; `2` = Soundlink managed; `3` = wallet. Public API write
2128
3123
  operations (budget changes, stop, tier updates) are supported for
2129
3124
  generation `3` only.
3125
+ artistId:
3126
+ type: string
3127
+ nullable: true
3128
+ description: |
3129
+ Follow-attribution Spotify artist ID (`artist_id_follow`).
3130
+ This is the artist campaign follows are credited to, not the
3131
+ track's credit list (collabs/features are omitted). Use this
3132
+ to group campaigns for one artist. `null` when unset.
3133
+ artistName:
3134
+ type: string
3135
+ nullable: true
3136
+ description: |
3137
+ Cached display name for `artistId` only — not derived from the
3138
+ track's artists. `null` when unknown or unset.
3139
+ trackId:
3140
+ type: string
3141
+ nullable: true
3142
+ description: |
3143
+ Promoted Spotify track ID, parsed from the smart link URL.
3144
+ `null` for playlist campaigns or when the URL is not a track.
3145
+ Stable join key for the song; same grain as
3146
+ `campaign_target_spotify_track_id` on metrics breakdown.
3147
+ playlistId:
3148
+ type: string
3149
+ nullable: true
3150
+ description: |
3151
+ Promoted Spotify playlist ID, parsed from the smart link URL.
3152
+ `null` for track campaigns or when the URL is not a playlist.
3153
+ Same grain as `campaign_target_playlist_id` on metrics breakdown.
3154
+ trackName:
3155
+ type: string
3156
+ nullable: true
3157
+ description: |
3158
+ Promoted track title. `null` for playlist campaigns or when unknown.
3159
+ campaignUrl:
3160
+ type: string
3161
+ format: uri
3162
+ description: |
3163
+ Logged-in campaign insights URL in the Soundlink product
3164
+ (`/orgs/{organizationId}/insights/{smartLinkId}`). Uses the smart
3165
+ link id, not the campaign id. Requires a Soundlink account in this
3166
+ organization. This is not a public share link.
2130
3167
  createdAt:
2131
3168
  type: string
2132
3169
  format: date-time
@@ -2144,6 +3181,19 @@ components:
2144
3181
  description: |
2145
3182
  Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
2146
3183
  Set at campaign creation.
3184
+ autoRenew:
3185
+ type: boolean
3186
+ description: |
3187
+ Whether this wallet campaign renews at the end of each cycle.
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.
2147
3197
 
2148
3198
  CampaignListResponse:
2149
3199
  type: object
@@ -2173,7 +3223,7 @@ components:
2173
3223
 
2174
3224
  CampaignTier:
2175
3225
  type: object
2176
- required: [tierId, tierName, isEnabled, allocationPercent]
3226
+ required: [tierId, tierName, isEnabled, allocationPercent, learningStatus]
2177
3227
  properties:
2178
3228
  tierId:
2179
3229
  type: integer
@@ -2189,6 +3239,13 @@ components:
2189
3239
  minimum: 0
2190
3240
  maximum: 100
2191
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.
2192
3249
 
2193
3250
  CampaignTiersData:
2194
3251
  type: object
@@ -2215,6 +3272,41 @@ components:
2215
3272
  meta:
2216
3273
  $ref: '#/components/schemas/Meta'
2217
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
+
2218
3310
  TierStatusUpdateItem:
2219
3311
  type: object
2220
3312
  required: [targetingTierId, isEnabled, newAllocationPercent]
@@ -2241,6 +3333,11 @@ components:
2241
3333
  minItems: 1
2242
3334
  items:
2243
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.
2244
3341
 
2245
3342
  Genre:
2246
3343
  type: string
@@ -2399,6 +3496,13 @@ components:
2399
3496
  cloned from. Records lineage only — it does not copy settings from
2400
3497
  the source; all other create fields must still be provided. Unknown
2401
3498
  or other-organization IDs return `400 invalid_request`.
3499
+ autoRenew:
3500
+ type: boolean
3501
+ default: false
3502
+ description: >-
3503
+ When true, the wallet campaign renews at the end of each cycle if
3504
+ credit remains. When false or omitted, auto-renew stays off. A
3505
+ renewal can cost more than create because of ad fees.
2402
3506
 
2403
3507
  CreateCampaignRequestWithoutTiers:
2404
3508
  allOf:
@@ -2445,12 +3549,15 @@ components:
2445
3549
 
2446
3550
  CampaignCreateData:
2447
3551
  type: object
2448
- required: [campaignId, status]
3552
+ required: [campaignId, status, autoRenew]
2449
3553
  properties:
2450
3554
  campaignId:
2451
3555
  type: string
2452
3556
  status:
2453
3557
  $ref: '#/components/schemas/CampaignStatus'
3558
+ autoRenew:
3559
+ type: boolean
3560
+ description: Stored auto-renew flag for this wallet campaign.
2454
3561
 
2455
3562
  CreateCampaignResponse:
2456
3563
  type: object
@@ -2469,7 +3576,10 @@ components:
2469
3576
  type: string
2470
3577
  status:
2471
3578
  $ref: '#/components/schemas/CampaignStatus'
2472
- description: Campaign status after stop (typically `stopped`).
3579
+ description: |
3580
+ Campaign status after stop. `stopped` when stop applied or the
3581
+ campaign was already stopped. `ended` when the campaign had
3582
+ already ended.
2473
3583
 
2474
3584
  StopCampaignResponse:
2475
3585
  type: object
@@ -2480,6 +3590,31 @@ components:
2480
3590
  meta:
2481
3591
  $ref: '#/components/schemas/Meta'
2482
3592
 
3593
+ UpdateCampaignAutoRenewRequest:
3594
+ type: object
3595
+ required: [autoRenew]
3596
+ properties:
3597
+ autoRenew:
3598
+ type: boolean
3599
+
3600
+ CampaignAutoRenewData:
3601
+ type: object
3602
+ required: [campaignId, autoRenew]
3603
+ properties:
3604
+ campaignId:
3605
+ type: string
3606
+ autoRenew:
3607
+ type: boolean
3608
+
3609
+ UpdateCampaignAutoRenewResponse:
3610
+ type: object
3611
+ required: [data, meta]
3612
+ properties:
3613
+ data:
3614
+ $ref: '#/components/schemas/CampaignAutoRenewData'
3615
+ meta:
3616
+ $ref: '#/components/schemas/Meta'
3617
+
2483
3618
  StrategyCatalogItem:
2484
3619
  type: object
2485
3620
  required: [strategyType, tierTargetingAllowed]
@@ -2576,10 +3711,12 @@ components:
2576
3711
  properties:
2577
3712
  targetDailyBudget:
2578
3713
  type: number
2579
- minimum: 10
3714
+ minimum: 0
3715
+ exclusiveMinimum: true
2580
3716
  description: |
2581
- New daily budget in USD (gross). Must be at least `$10`/day and
2582
- lower than the campaign's current daily budget.
3717
+ New daily budget in USD (gross). Must be at least the campaign's
3718
+ enabled-ad-set minimum gross and lower than the campaign's current
3719
+ daily budget.
2583
3720
  mode:
2584
3721
  $ref: '#/components/schemas/BudgetDecreaseMode'
2585
3722
 
@@ -2620,12 +3757,15 @@ components:
2620
3757
  MetricsOverview:
2621
3758
  type: object
2622
3759
  description: |
2623
- Campaign-level totals aggregated across all countries for the requested
2624
- date range. Field names align with the `campaign_country_daily` row
2625
- 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.
2626
3765
  required:
2627
3766
  [
2628
3767
  listeners,
3768
+ total_listeners,
2629
3769
  streams,
2630
3770
  followers,
2631
3771
  spend_media,
@@ -2639,7 +3779,14 @@ components:
2639
3779
  properties:
2640
3780
  listeners:
2641
3781
  type: integer
2642
- 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`.
2643
3790
  streams:
2644
3791
  type: integer
2645
3792
  description: Attributed Spotify streams (sum of country rows).
@@ -2672,13 +3819,15 @@ components:
2672
3819
  description: Currency for spend fields. Currently always `USD`.
2673
3820
  cpl:
2674
3821
  type: number
2675
- description: Cost per listener (spend_media / listeners).
3822
+ description: Cost per new listener (spend_media / listeners).
2676
3823
  cpf:
2677
3824
  type: number
2678
3825
  description: Cost per follower (spend_media / followers).
2679
3826
  streams_per_listener:
2680
3827
  type: number
2681
- 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.
2682
3831
 
2683
3832
  MetricsOverviewResponse:
2684
3833
  type: object
@@ -2689,50 +3838,231 @@ components:
2689
3838
  meta:
2690
3839
  $ref: '#/components/schemas/Meta'
2691
3840
 
2692
- BreakdownRow:
3841
+ CreativeMetricsChild:
2693
3842
  type: object
2694
- description: |
2695
- One row of the `campaign_country_daily` v1.0 schema.
2696
- Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
2697
- Rows are idempotent — re-ingesting on the primary key is safe.
2698
- Values for a given `report_date` may be revised for up to 7 days after
2699
- the date closes due to delayed events from Meta and Spotify.
2700
3843
  required:
2701
- - provider
2702
- - account_id
2703
- - schema_version
2704
- - report_date
2705
- - report_date_timezone
2706
- - exported_at
2707
- - campaign_id
2708
- - campaign_name
2709
- - campaign_target_type
2710
- - country_code
2711
- - streams
3844
+ - caption
3845
+ - language
3846
+ - spotify_track_id
3847
+ - timestamp_start_ms
3848
+ - timestamp_end_ms
2712
3849
  - listeners
2713
3850
  - followers
2714
- - streams_per_listener
2715
- - spend_media
2716
- - spend_total
2717
- - fees
2718
- - currency
2719
- - currency_account
3851
+ - link_clicks
2720
3852
  - cpl
2721
3853
  - cpf
2722
- - cost_per_result
3854
+ - cpc_linkclick
3855
+ - frequency
2723
3856
  properties:
2724
- provider:
2725
- type: string
2726
- enum: [soundlink]
2727
- description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
2728
- account_id:
3857
+ caption:
2729
3858
  type: string
2730
- description: Soundlink organization ID (UUID).
2731
- schema_version:
3859
+ nullable: true
3860
+ language:
2732
3861
  type: string
2733
- description: Schema version. Pin your ingest pipeline to this value.
2734
- example: '1.0'
2735
- report_date:
3862
+ nullable: true
3863
+ description: Render language. Null when the render has no language.
3864
+ spotify_track_id:
3865
+ type: string
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.
3879
+ listeners:
3880
+ type: integer
3881
+ nullable: true
3882
+ description: Lifetime listeners. Null when the variant has no performance row.
3883
+ followers:
3884
+ type: integer
3885
+ nullable: true
3886
+ link_clicks:
3887
+ type: integer
3888
+ nullable: true
3889
+ cpl:
3890
+ type: number
3891
+ nullable: true
3892
+ cpf:
3893
+ type: number
3894
+ nullable: true
3895
+ cpc_linkclick:
3896
+ type: number
3897
+ nullable: true
3898
+ frequency:
3899
+ type: number
3900
+ nullable: true
3901
+
3902
+ CreativeMetricsGroup:
3903
+ type: object
3904
+ required:
3905
+ - video_id
3906
+ - caption
3907
+ - listeners
3908
+ - followers
3909
+ - link_clicks
3910
+ - cpl
3911
+ - cpf
3912
+ - cpc_linkclick
3913
+ - frequency
3914
+ - children
3915
+ properties:
3916
+ video_id:
3917
+ type: string
3918
+ description: Background video id. Groups with no video id are omitted.
3919
+ caption:
3920
+ type: string
3921
+ nullable: true
3922
+ description: Caption of the highest-spend child.
3923
+ listeners:
3924
+ type: integer
3925
+ nullable: true
3926
+ followers:
3927
+ type: integer
3928
+ nullable: true
3929
+ link_clicks:
3930
+ type: integer
3931
+ nullable: true
3932
+ cpl:
3933
+ type: number
3934
+ nullable: true
3935
+ cpf:
3936
+ type: number
3937
+ nullable: true
3938
+ cpc_linkclick:
3939
+ type: number
3940
+ nullable: true
3941
+ frequency:
3942
+ type: number
3943
+ nullable: true
3944
+ children:
3945
+ type: array
3946
+ minItems: 1
3947
+ items:
3948
+ $ref: '#/components/schemas/CreativeMetricsChild'
3949
+
3950
+ CreativeMetrics:
3951
+ type: object
3952
+ required: [creatives]
3953
+ properties:
3954
+ creatives:
3955
+ type: array
3956
+ items:
3957
+ $ref: '#/components/schemas/CreativeMetricsGroup'
3958
+
3959
+ CreativeMetricsResponse:
3960
+ type: object
3961
+ required: [data, meta]
3962
+ properties:
3963
+ data:
3964
+ $ref: '#/components/schemas/CreativeMetrics'
3965
+ meta:
3966
+ $ref: '#/components/schemas/Meta'
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
+
4019
+ BreakdownRow:
4020
+ type: object
4021
+ description: |
4022
+ One row of the `campaign_country_daily` v1.1 schema.
4023
+ Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
4024
+ Rows are idempotent — re-ingesting on the primary key is safe.
4025
+ Values for a given `report_date` may be revised for up to 7 days after
4026
+ the date closes due to delayed events from Meta and Spotify.
4027
+ required:
4028
+ - provider
4029
+ - account_id
4030
+ - schema_version
4031
+ - report_date
4032
+ - report_date_timezone
4033
+ - exported_at
4034
+ - campaign_id
4035
+ - campaign_name
4036
+ - campaign_target_type
4037
+ - country_code
4038
+ - streams
4039
+ - listeners
4040
+ - new_listeners
4041
+ - returning_listeners
4042
+ - total_listeners
4043
+ - followers
4044
+ - streams_per_listener
4045
+ - spend_media
4046
+ - spend_total
4047
+ - fees
4048
+ - currency
4049
+ - currency_account
4050
+ - cpl
4051
+ - cpf
4052
+ - cost_per_result
4053
+ properties:
4054
+ provider:
4055
+ type: string
4056
+ enum: [soundlink]
4057
+ description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
4058
+ account_id:
4059
+ type: string
4060
+ description: Soundlink organization ID (UUID).
4061
+ schema_version:
4062
+ type: string
4063
+ description: Schema version. Pin your ingest pipeline to this value. `1.1` adds listener splits.
4064
+ example: '1.1'
4065
+ report_date:
2736
4066
  type: string
2737
4067
  format: date
2738
4068
  description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
@@ -2781,19 +4111,34 @@ components:
2781
4111
  link_clicks:
2782
4112
  type: integer
2783
4113
  nullable: true
2784
- description: Clicks on "Continue with Spotify" on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR.
4114
+ description: CTA clicks across all DSPs on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR.
2785
4115
  streams:
2786
4116
  type: integer
2787
4117
  description: Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.
2788
4118
  listeners:
2789
4119
  type: integer
2790
- 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.
2791
4134
  followers:
2792
4135
  type: integer
2793
4136
  description: Spotify artist follower gains attributed to this campaign in this country on this day (7-day click-through window).
2794
4137
  streams_per_listener:
2795
4138
  type: number
2796
- 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.
2797
4142
  spend_media:
2798
4143
  type: number
2799
4144
  description: Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In `currency`.
@@ -2811,7 +4156,7 @@ components:
2811
4156
  description: Account billing currency. Currently always `USD`. Will differ from `currency` once EUR delivery is available.
2812
4157
  cpl:
2813
4158
  type: number
2814
- 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.
2815
4160
  cpf:
2816
4161
  type: number
2817
4162
  description: Cost per follower (spend_media / followers). Zero if followers is zero.
@@ -3106,33 +4451,89 @@ components:
3106
4451
  spotifyUrl:
3107
4452
  type: string
3108
4453
  format: uri
3109
- description: HTTPS Spotify track or playlist URL.
4454
+ description: |
4455
+ HTTPS Spotify track or playlist URL. Album, artist, and URI
4456
+ (`spotify:track:...`) forms are rejected. An optional `intl-xx`
4457
+ path segment is accepted. Query strings are stripped before
4458
+ lookup. The resource must currently exist on Spotify.
3110
4459
  example: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
3111
4460
  autoFollow:
3112
4461
  type: boolean
3113
4462
  default: false
4463
+ description: |
4464
+ When true, fans who connect Spotify from the landing page are
4465
+ asked to follow the track artist (`artistIdFollow`, or the
4466
+ track's primary artist when omitted), or the playlist itself
4467
+ when `spotifyUrl` is a playlist. Defaults to false.
3114
4468
  artistIdFollow:
3115
4469
  type: string
4470
+ description: |
4471
+ Spotify artist ID used for auto-follow on track links.
4472
+ Optional. Persisted even when `autoFollow` is false. For
4473
+ multi-artist tracks, pass the artist that should be followed.
4474
+ Ignored when `spotifyUrl` is a playlist.
3116
4475
  metaPixelId:
3117
4476
  type: string
4477
+ description: |
4478
+ Meta pixel ID. Must be sent together with
4479
+ `metaConversionAccessToken`. Omit both to skip Meta tracking.
3118
4480
  metaConversionAccessToken:
3119
4481
  type: string
3120
4482
  writeOnly: true
3121
4483
  description: |
3122
4484
  Meta Conversions API access token. Write-only: accepted on create,
3123
4485
  never returned on GET. Must be sent together with `metaPixelId`.
4486
+ appleMusicUrl:
4487
+ type: string
4488
+ format: uri
4489
+ description: |
4490
+ Optional HTTPS Apple Music URL. Accepted shapes: a song
4491
+ (`/song/{slug}/{id}`), a catalog playlist (`pl.`), a library
4492
+ playlist (`pl.u-`), or an album share-sheet link with `?i={songId}`
4493
+ (stored as the canonical song URL). Host must be `music.apple.com`
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.
4499
+ example: https://music.apple.com/us/song/anti-hero/1645937493
4500
+ youtubeMusicUrl:
4501
+ type: string
4502
+ format: uri
4503
+ description: |
4504
+ Optional HTTPS YouTube Music URL. Accepted shapes: a song
4505
+ (`music.youtube.com/watch?v=…`, `youtube.com/watch?v=…`, or
4506
+ `youtu.be/…`) or a playlist (`…/playlist?list=…`). Shorts,
4507
+ live, channel, and browse links are rejected. A video or
4508
+ playlist that does not exist on YouTube returns
4509
+ `400 invalid_request`. Quota, auth, or upstream failures warn and
4510
+ allow create. Omit to leave YouTube Music unset.
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`.
3124
4520
 
3125
4521
  SoundlinkDetail:
3126
4522
  allOf:
3127
4523
  - $ref: '#/components/schemas/SoundlinkSummary'
3128
4524
  - type: object
3129
- required: [autoFollow, artistIdFollow, metaPixelId, tiktokPixelId]
4525
+ required:
4526
+ - autoFollow
4527
+ - artistIdFollow
4528
+ - metaPixelId
4529
+ - tiktokPixelId
4530
+ - appleMusicUrl
4531
+ - youtubeMusicUrl
4532
+ - attributionEnabled
3130
4533
  properties:
3131
4534
  autoFollow:
3132
4535
  type: boolean
3133
- description: |
3134
- Whether auto-follow is configured for this soundlink. Whether
3135
- it takes effect also depends on the organization's plan.
4536
+ description: Whether auto-follow is enabled on this soundlink.
3136
4537
  artistIdFollow:
3137
4538
  type: string
3138
4539
  nullable: true
@@ -3147,6 +4548,26 @@ components:
3147
4548
  type: string
3148
4549
  nullable: true
3149
4550
  description: TikTok pixel ID configured on this soundlink. `null` if not set.
4551
+ appleMusicUrl:
4552
+ type: string
4553
+ format: uri
4554
+ nullable: true
4555
+ description: |
4556
+ Apple Music URL stored on this soundlink. `null` if not set.
4557
+ Share-sheet album links are returned as the canonical song URL.
4558
+ youtubeMusicUrl:
4559
+ type: string
4560
+ format: uri
4561
+ nullable: true
4562
+ description: |
4563
+ YouTube Music URL stored on this soundlink. `null` if not set.
4564
+ Input hosts such as `youtu.be` are returned as the canonical
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.
3150
4571
 
3151
4572
  SoundlinkDetailResponse:
3152
4573
  type: object
@@ -3157,6 +4578,24 @@ components:
3157
4578
  meta:
3158
4579
  $ref: '#/components/schemas/Meta'
3159
4580
 
4581
+ SendTestEventResponse:
4582
+ type: object
4583
+ required: [data, meta]
4584
+ properties:
4585
+ data:
4586
+ type: object
4587
+ required: [soundlinkId, status]
4588
+ properties:
4589
+ soundlinkId:
4590
+ type: string
4591
+ description: Soundlink that received the test event.
4592
+ status:
4593
+ type: string
4594
+ enum: [sent]
4595
+ description: Present when the stored pixel test event was sent.
4596
+ meta:
4597
+ $ref: '#/components/schemas/Meta'
4598
+
3160
4599
  SoundlinkMetricsOverview:
3161
4600
  type: object
3162
4601
  description: |
@@ -3171,8 +4610,8 @@ components:
3171
4610
  type: integer
3172
4611
  nullable: true
3173
4612
  description: |
3174
- Clicks on "Continue with Spotify" on the landing page — outbound
3175
- clicks to Spotify. Null if not tracked for this soundlink type.
4613
+ CTA clicks across all DSPs on the landing page. Null if not tracked
4614
+ for this soundlink type.
3176
4615
  streams:
3177
4616
  type: integer
3178
4617
  description: Attributed Spotify streams (sum of country-day rows).
@@ -3206,16 +4645,15 @@ components:
3206
4645
  meta:
3207
4646
  $ref: '#/components/schemas/Meta'
3208
4647
 
3209
- SoundlinkDailyRow:
4648
+ SoundlinkCountryDailyRow:
3210
4649
  type: object
3211
4650
  description: |
3212
- One row of the `soundlink_daily` v1.0 schema.
3213
- Primary key: `(provider, account_id, report_date, soundlink_id)`.
4651
+ One row of the `soundlink_country_daily` v1.0 schema.
4652
+ Primary key: `(provider, account_id, report_date, soundlink_id, country_code)`.
3214
4653
  Rows are idempotent — re-ingesting on the primary key is safe.
3215
4654
  Values for a given `report_date` may be revised for up to 7 days after
3216
4655
  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.
4656
+ Rows contain no financial fields.
3219
4657
  required:
3220
4658
  - provider
3221
4659
  - account_id
@@ -3226,6 +4664,7 @@ components:
3226
4664
  - soundlink_id
3227
4665
  - soundlink_name
3228
4666
  - soundlink_target_type
4667
+ - country_code
3229
4668
  - views
3230
4669
  - streams
3231
4670
  - listeners
@@ -3279,47 +4718,51 @@ components:
3279
4718
  type: string
3280
4719
  nullable: true
3281
4720
  description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
4721
+ country_code:
4722
+ type: string
4723
+ description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
3282
4724
  views:
3283
4725
  type: integer
3284
- description: Soundlink landing page views on this day.
4726
+ description: Soundlink landing page views in this country on this day.
3285
4727
  link_clicks:
3286
4728
  type: integer
3287
4729
  nullable: true
3288
4730
  description: |
3289
- Clicks on "Continue with Spotify" on the landing page — outbound
3290
- clicks to Spotify. Null if not tracked for this soundlink type.
4731
+ CTA clicks across all DSPs on the landing page. Null if not tracked
4732
+ for this soundlink type.
3291
4733
  streams:
3292
4734
  type: integer
3293
4735
  description: |
3294
- Spotify streams attributed to this soundlink on this day:
3295
- `new_listener_streams + returning_listener_streams`. Observed
4736
+ Spotify streams attributed to this soundlink in this country on this
4737
+ day: `new_listener_streams + returning_listener_streams`. Observed
3296
4738
  Spotify-side events, not modelled estimates. Safe to sum within a
3297
4739
  day; summing across days counts repeat listens.
3298
4740
  listeners:
3299
4741
  type: integer
3300
4742
  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.
4743
+ Unique Spotify listeners attributed to this soundlink in this
4744
+ country on this day: `new_listeners + returning_listeners`.
4745
+ **Do not sum across days** — the same listener can appear on
4746
+ multiple `report_date` rows.
3304
4747
  new_listeners:
3305
4748
  type: integer
3306
4749
  nullable: true
3307
- description: Unique listeners whose first play via this soundlink occurred on `report_date`.
4750
+ description: Unique listeners whose first play via this soundlink occurred on `report_date` in this country.
3308
4751
  returning_listeners:
3309
4752
  type: integer
3310
4753
  nullable: true
3311
- description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
4754
+ description: Unique listeners who played on `report_date` in this country but whose first play was on an earlier date.
3312
4755
  new_listener_streams:
3313
4756
  type: integer
3314
4757
  nullable: true
3315
- description: Stream count from new listeners on `report_date`.
4758
+ description: Stream count from new listeners on `report_date` in this country.
3316
4759
  returning_listener_streams:
3317
4760
  type: integer
3318
4761
  nullable: true
3319
- description: Stream count from returning listeners on `report_date`.
4762
+ description: Stream count from returning listeners on `report_date` in this country.
3320
4763
  followers:
3321
4764
  type: integer
3322
- description: Spotify artist follower gains attributed to this soundlink on this day.
4765
+ description: Spotify artist follower gains attributed to this soundlink in this country on this day.
3323
4766
  streams_per_listener:
3324
4767
  type: number
3325
4768
  description: streams / listeners for this row. Zero if listeners is zero.
@@ -3332,7 +4775,7 @@ components:
3332
4775
  with `ctr_linkclick` from `campaign_country_daily`. Null if views
3333
4776
  is zero or link_clicks is null.
3334
4777
 
3335
- SoundlinkTimeseriesResponse:
4778
+ SoundlinkBreakdownResponse:
3336
4779
  type: object
3337
4780
  required: [data, meta]
3338
4781
  properties:
@@ -3342,26 +4785,48 @@ components:
3342
4785
  properties:
3343
4786
  schemaVersion:
3344
4787
  type: string
3345
- description: Version of the `soundlink_daily` row schema. Pin your ingest pipeline to this.
4788
+ description: Version of the `soundlink_country_daily` row schema. Pin your ingest pipeline to this.
3346
4789
  example: '1.0'
3347
4790
  items:
3348
4791
  type: array
3349
4792
  items:
3350
- $ref: '#/components/schemas/SoundlinkDailyRow'
4793
+ $ref: '#/components/schemas/SoundlinkCountryDailyRow'
3351
4794
  pagination:
3352
4795
  $ref: '#/components/schemas/Pagination'
3353
4796
  meta:
3354
4797
  $ref: '#/components/schemas/Meta'
3355
4798
 
3356
- SoundlinkCountryDailyRow:
4799
+ SoundlinkEngagementResponse:
4800
+ type: object
4801
+ required: [data, meta]
4802
+ properties:
4803
+ data:
4804
+ type: object
4805
+ required: [schemaVersion, items, pagination]
4806
+ properties:
4807
+ schemaVersion:
4808
+ type: string
4809
+ description: Version of the `soundlink_engagement_daily` row schema. Pin your ingest pipeline to this.
4810
+ example: '1.0'
4811
+ items:
4812
+ type: array
4813
+ items:
4814
+ $ref: '#/components/schemas/SoundlinkEngagementDailyRow'
4815
+ pagination:
4816
+ $ref: '#/components/schemas/Pagination'
4817
+ meta:
4818
+ $ref: '#/components/schemas/Meta'
4819
+
4820
+ SoundlinkEngagementDailyRow:
3357
4821
  type: object
3358
4822
  description: |
3359
- One row of the `soundlink_country_daily` v1.0 schema.
3360
- Primary key: `(provider, account_id, report_date, soundlink_id, country_code)`.
4823
+ One row of the `soundlink_engagement_daily` v1.0 schema.
4824
+ Primary key: `(provider, account_id, report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
3361
4825
  Rows are idempotent — re-ingesting on the primary key is safe.
3362
4826
  Values for a given `report_date` may be revised for up to 7 days after
3363
4827
  the date closes due to delayed Spotify playback events.
3364
- Rows contain no financial fields.
4828
+ No `status` field: soundlinks do not store per-day lifecycle history.
4829
+ No financial fields.
3365
4830
  required:
3366
4831
  - provider
3367
4832
  - account_id
@@ -3372,14 +4837,19 @@ components:
3372
4837
  - soundlink_id
3373
4838
  - soundlink_name
3374
4839
  - soundlink_target_type
4840
+ - engagement_context
3375
4841
  - country_code
3376
- - views
3377
- - streams
4842
+ - engaged_spotify_track_id
4843
+ - engaged_track_name
4844
+ - new_listeners
4845
+ - returning_listeners
3378
4846
  - listeners
3379
- - followers
3380
- - streams_per_listener
3381
- properties:
3382
- provider:
4847
+ - new_listener_streams
4848
+ - returning_listener_streams
4849
+ - streams
4850
+ - spl
4851
+ properties:
4852
+ provider:
3383
4853
  type: string
3384
4854
  enum: [soundlink]
3385
4855
  description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
@@ -3388,12 +4858,12 @@ components:
3388
4858
  description: Soundlink organization ID (UUID).
3389
4859
  schema_version:
3390
4860
  type: string
3391
- description: Schema version. Pin your ingest pipeline to this value.
4861
+ description: Schema version string. Pin your ingest pipeline to this value.
3392
4862
  example: '1.0'
3393
4863
  report_date:
3394
4864
  type: string
3395
4865
  format: date
3396
- description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
4866
+ description: UTC calendar date the metrics belong to (`YYYY-MM-DD`). Rows can change for up to 7 days after close.
3397
4867
  report_date_timezone:
3398
4868
  type: string
3399
4869
  enum: [UTC]
@@ -3426,136 +4896,121 @@ components:
3426
4896
  type: string
3427
4897
  nullable: true
3428
4898
  description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
4899
+ engagement_context:
4900
+ type: string
4901
+ enum: [catalog, playlist]
4902
+ description: |
4903
+ Which section this row belongs to.
4904
+ `catalog`: plays of the promoted track and same-artist catalog tracks (track soundlinks).
4905
+ `playlist`: per-track performance inside the promoted playlist (playlist soundlinks).
3429
4906
  country_code:
3430
4907
  type: string
3431
4908
  description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
3432
- views:
3433
- type: integer
3434
- description: Soundlink landing page views in this country on this day.
3435
- link_clicks:
3436
- type: integer
4909
+ example: US
4910
+ engaged_track_isrc:
4911
+ type: string
3437
4912
  nullable: true
3438
4913
  description: |
3439
- Clicks on "Continue with Spotify" on the landing page — outbound
3440
- clicks to Spotify. Null if not tracked for this soundlink type.
3441
- streams:
3442
- type: integer
3443
- description: |
3444
- Spotify streams attributed to this soundlink in this country on this
3445
- day: `new_listener_streams + returning_listener_streams`. Observed
3446
- Spotify-side events, not modelled estimates. Safe to sum within a
3447
- day; summing across days counts repeat listens.
3448
- listeners:
4914
+ ISRC of the track that received listens. May differ from `soundlink_target_isrc`
4915
+ for catalog spillover rows. `null` if ISRC could not be resolved.
4916
+ engaged_spotify_track_id:
4917
+ type: string
4918
+ description: Spotify track ID of the engaged track. Part of the primary key.
4919
+ example: 4cOdK2wGLETKBW3PvgPWqT
4920
+ engaged_track_name:
4921
+ type: string
4922
+ description: Display name of the engaged track.
4923
+ playlist_position:
3449
4924
  type: integer
4925
+ nullable: true
4926
+ minimum: 1
3450
4927
  description: |
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.
4928
+ 1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
4929
+ Populated only when `engagement_context = playlist`. Treat `null` as unavailable, not an error.
3455
4930
  new_listeners:
3456
4931
  type: integer
3457
- nullable: true
3458
- description: Unique listeners whose first play via this soundlink occurred on `report_date` in this country.
4932
+ minimum: 0
4933
+ description: Unique listeners whose first play of this track via this soundlink occurred on `report_date`.
3459
4934
  returning_listeners:
3460
4935
  type: integer
3461
- nullable: true
3462
- description: Unique listeners who played on `report_date` in this country but whose first play was on an earlier date.
4936
+ minimum: 0
4937
+ description: Unique listeners who played this track on `report_date` but whose first play was on an earlier date.
4938
+ listeners:
4939
+ type: integer
4940
+ minimum: 0
4941
+ description: |
4942
+ Total unique listeners on `report_date`: `new_listeners + returning_listeners`.
4943
+ **Do not sum across days** — the same listener can appear on multiple `report_date` rows.
3463
4944
  new_listener_streams:
3464
4945
  type: integer
3465
- nullable: true
3466
- description: Stream count from new listeners on `report_date` in this country.
4946
+ minimum: 0
4947
+ description: Stream count from new listeners on `report_date`.
3467
4948
  returning_listener_streams:
3468
4949
  type: integer
3469
- nullable: true
3470
- description: Stream count from returning listeners on `report_date` in this country.
3471
- followers:
4950
+ minimum: 0
4951
+ description: Stream count from returning listeners on `report_date`.
4952
+ streams:
3472
4953
  type: integer
3473
- description: Spotify artist follower gains attributed to this soundlink in this country on this day.
3474
- streams_per_listener:
3475
- type: number
3476
- description: streams / listeners for this row. Zero if listeners is zero.
3477
- ctr_lp:
3478
- type: number
3479
- nullable: true
4954
+ minimum: 0
3480
4955
  description: |
3481
- Landing page click-through rate (link_clicks / views). Computed
3482
- against landing page views, not ad impressions — do not combine
3483
- with `ctr_linkclick` from `campaign_country_daily`. Null if views
3484
- is zero or link_clicks is null.
3485
-
3486
- SoundlinkBreakdownResponse:
3487
- type: object
3488
- required: [data, meta]
3489
- properties:
3490
- data:
3491
- type: object
3492
- required: [schemaVersion, items, pagination]
3493
- properties:
3494
- schemaVersion:
3495
- type: string
3496
- description: Version of the `soundlink_country_daily` row schema. Pin your ingest pipeline to this.
3497
- example: '1.0'
3498
- items:
3499
- type: array
3500
- items:
3501
- $ref: '#/components/schemas/SoundlinkCountryDailyRow'
3502
- pagination:
3503
- $ref: '#/components/schemas/Pagination'
3504
- meta:
3505
- $ref: '#/components/schemas/Meta'
4956
+ Total streams on `report_date`: `new_listener_streams + returning_listener_streams`.
4957
+ Safe to sum within a day; summing across days counts repeat listens.
4958
+ spl:
4959
+ type: number
4960
+ description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
3506
4961
 
3507
- SoundlinkEngagementResponse:
4962
+ SoundlinkCohortRetentionResponse:
3508
4963
  type: object
3509
4964
  required: [data, meta]
3510
4965
  properties:
3511
4966
  data:
3512
4967
  type: object
3513
- required: [schemaVersion, items, pagination]
4968
+ required: [schemaVersion, items]
3514
4969
  properties:
3515
4970
  schemaVersion:
3516
4971
  type: string
3517
- description: Version of the `soundlink_engagement_daily` row schema. Pin your ingest pipeline to this.
4972
+ description: Version of the `soundlink_cohort_retention_daily` row schema. Pin your ingest pipeline to this.
3518
4973
  example: '1.0'
3519
4974
  items:
3520
4975
  type: array
3521
4976
  items:
3522
- $ref: '#/components/schemas/SoundlinkEngagementDailyRow'
3523
- pagination:
3524
- $ref: '#/components/schemas/Pagination'
4977
+ $ref: '#/components/schemas/SoundlinkCohortRetentionDailyRow'
3525
4978
  meta:
3526
4979
  $ref: '#/components/schemas/Meta'
3527
4980
 
3528
- SoundlinkEngagementDailyRow:
4981
+ SoundlinkCohortRetentionDailyRow:
3529
4982
  type: object
3530
4983
  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.
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`.
3538
4989
  required:
3539
4990
  - provider
3540
4991
  - account_id
3541
4992
  - schema_version
3542
- - report_date
3543
- - report_date_timezone
4993
+ - cohort_date
4994
+ - cohort_date_timezone
3544
4995
  - exported_at
3545
4996
  - soundlink_id
3546
4997
  - soundlink_name
3547
4998
  - 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
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
3559
5014
  properties:
3560
5015
  provider:
3561
5016
  type: string
@@ -3568,18 +5023,18 @@ components:
3568
5023
  type: string
3569
5024
  description: Schema version string. Pin your ingest pipeline to this value.
3570
5025
  example: '1.0'
3571
- report_date:
5026
+ cohort_date:
3572
5027
  type: string
3573
5028
  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:
5029
+ description: UTC calendar date (`YYYY-MM-DD`) on which this cohort's listeners first played via the soundlink.
5030
+ cohort_date_timezone:
3576
5031
  type: string
3577
5032
  enum: [UTC]
3578
5033
  description: Always `UTC`.
3579
5034
  exported_at:
3580
5035
  type: string
3581
5036
  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.
5037
+ description: ISO 8601 UTC timestamp when this row was generated.
3583
5038
  soundlink_id:
3584
5039
  type: string
3585
5040
  description: Unique ID of this soundlink.
@@ -3595,7 +5050,7 @@ components:
3595
5050
  soundlink_target_isrc:
3596
5051
  type: string
3597
5052
  nullable: true
3598
- description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
5053
+ description: ISRC of the promoted track. Currently always `null`.
3599
5054
  soundlink_target_spotify_track_id:
3600
5055
  type: string
3601
5056
  nullable: true
@@ -3604,68 +5059,87 @@ components:
3604
5059
  type: string
3605
5060
  nullable: true
3606
5061
  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:
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:
3632
5067
  type: integer
3633
5068
  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:
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:
3639
5078
  type: integer
5079
+ nullable: true
3640
5080
  minimum: 0
3641
- description: Unique listeners whose first play of this track via this soundlink occurred on `report_date`.
3642
- returning_listeners:
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:
3643
5089
  type: integer
5090
+ nullable: true
3644
5091
  minimum: 0
3645
- description: Unique listeners who played this track on `report_date` but whose first play was on an earlier date.
3646
- listeners:
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:
3647
5100
  type: integer
5101
+ nullable: true
3648
5102
  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:
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:
3653
5111
  type: integer
5112
+ nullable: true
3654
5113
  minimum: 0
3655
- description: Stream count from new listeners on `report_date`.
3656
- returning_listener_streams:
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:
3657
5122
  type: integer
5123
+ nullable: true
3658
5124
  minimum: 0
3659
- description: Stream count from returning listeners on `report_date`.
3660
- streams:
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:
3661
5133
  type: integer
5134
+ nullable: true
3662
5135
  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:
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:
3667
5138
  type: number
3668
- description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
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.
3669
5143
 
3670
5144
  # --- Videos ---
3671
5145
 
@@ -3677,7 +5151,7 @@ components:
3677
5151
  url:
3678
5152
  type: string
3679
5153
  format: uri
3680
- description: Public HTTPS URL to an MP4 file (max 50 MB). Mutually exclusive with `videos`.
5154
+ description: Public HTTPS URL to an MP4 or QuickTime (.mov) file (max 50 MB). Mutually exclusive with `videos`.
3681
5155
  videos:
3682
5156
  type: array
3683
5157
  minItems: 1
@@ -3690,7 +5164,7 @@ components:
3690
5164
  url:
3691
5165
  type: string
3692
5166
  format: uri
3693
- description: Public HTTPS URL to an MP4 file (max 50 MB).
5167
+ description: Public HTTPS URL to an MP4 or QuickTime (.mov) file (max 50 MB).
3694
5168
 
3695
5169
  VideoImportStatus:
3696
5170
  type: string
@@ -3903,6 +5377,31 @@ components:
3903
5377
  meta:
3904
5378
  requestId: 550e8400-e29b-41d4-a716-446655440000
3905
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
+
3906
5405
  CreateCampaignForbidden:
3907
5406
  description: |
3908
5407
  Valid key but missing the `campaigns:write` scope, or the calling
@@ -3927,142 +5426,237 @@ components:
3927
5426
  meta:
3928
5427
  requestId: 550e8400-e29b-41d4-a716-446655440000
3929
5428
 
3930
- InsufficientCredit:
3931
- description: Wallet balance is too low to cover `dailyBudget * durationDays`
5429
+ CreateSoundlinkBadRequest:
5430
+ description: |
5431
+ Missing or malformed request body, or a missing/empty
5432
+ `Idempotency-Key` header.
3932
5433
  content:
3933
5434
  application/json:
3934
5435
  schema:
3935
5436
  $ref: '#/components/schemas/ErrorResponse'
3936
- example:
3937
- error:
3938
- code: insufficient_credit
3939
- message: 'Insufficient wallet balance for this campaign.'
3940
- details:
3941
- available: 120.00
3942
- required: 350.00
3943
- meta:
3944
- requestId: 550e8400-e29b-41d4-a716-446655440000
5437
+ examples:
5438
+ missing_field:
5439
+ value:
5440
+ error:
5441
+ code: invalid_request
5442
+ message: 'Missing required field: name.'
5443
+ meta:
5444
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5445
+ missing_idempotency_key:
5446
+ value:
5447
+ error:
5448
+ code: invalid_request
5449
+ message: 'Idempotency-Key header is required and must not be empty.'
5450
+ meta:
5451
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5452
+ pixel_pair:
5453
+ value:
5454
+ error:
5455
+ code: invalid_request
5456
+ message: 'metaPixelId and metaConversionAccessToken must both be provided, or both omitted.'
5457
+ meta:
5458
+ requestId: 550e8400-e29b-41d4-a716-446655440000
3945
5459
 
3946
- CreateCampaignUnprocessable:
3947
- description: Request body is well-formed but semantically invalid
5460
+ CreateSoundlinkForbidden:
5461
+ description: |
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.
3948
5465
  content:
3949
5466
  application/json:
3950
5467
  schema:
3951
5468
  $ref: '#/components/schemas/ErrorResponse'
3952
5469
  examples:
3953
- invalid_genre:
3954
- value:
3955
- error:
3956
- code: invalid_genre
3957
- message: 'genre must be one of the supported values.'
3958
- meta:
3959
- requestId: 550e8400-e29b-41d4-a716-446655440000
3960
- invalid_duration_or_budget:
5470
+ insufficient_scope:
3961
5471
  value:
3962
5472
  error:
3963
- code: invalid_duration_or_budget
3964
- message: 'dailyBudget and durationDays must be greater than 0.'
5473
+ code: insufficient_scope
5474
+ message: 'This key does not have the soundlinks:write scope.'
3965
5475
  meta:
3966
5476
  requestId: 550e8400-e29b-41d4-a716-446655440000
3967
- invalid_daily_budget:
5477
+ soundlink_plan_required:
3968
5478
  value:
3969
5479
  error:
3970
- code: invalid_daily_budget
3971
- message: 'dailyBudget must be at least 10 (USD per day).'
5480
+ code: soundlink_plan_required
5481
+ message: 'Creating a Soundlink requires a self-serve plan.'
3972
5482
  meta:
3973
5483
  requestId: 550e8400-e29b-41d4-a716-446655440000
3974
- invalid_duration_days:
5484
+ attribution_not_enabled:
3975
5485
  value:
3976
5486
  error:
3977
- code: invalid_duration_days
3978
- message: 'durationDays must be an integer from 7 to 30, or 60, or 90.'
5487
+ code: attribution_not_enabled
5488
+ message: 'This organization cannot create a soundlink with attribution off.'
3979
5489
  meta:
3980
5490
  requestId: 550e8400-e29b-41d4-a716-446655440000
5491
+ CreateSoundlinkUnprocessable:
5492
+ description: Request body is well-formed but the Spotify URL is invalid.
5493
+ content:
5494
+ application/json:
5495
+ schema:
5496
+ $ref: '#/components/schemas/ErrorResponse'
5497
+ examples:
3981
5498
  invalid_spotify_url:
3982
- summary: Malformed URL or Spotify track/playlist does not exist
5499
+ summary: Malformed URL, unsupported type, or Spotify resource does not exist
3983
5500
  value:
3984
5501
  error:
3985
5502
  code: invalid_spotify_url
3986
5503
  message: 'Spotify track not found.'
3987
5504
  meta:
3988
5505
  requestId: 550e8400-e29b-41d4-a716-446655440000
3989
- invalid_tier_budget_allocation:
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:
3990
5517
  value:
3991
5518
  error:
3992
- code: invalid_tier_budget_allocation
3993
- message: 'tierTargeting.customTiers[].percentBudget must sum to 100.'
5519
+ code: insufficient_scope
5520
+ message: 'This key does not have the campaigns:write scope.'
3994
5521
  meta:
3995
5522
  requestId: 550e8400-e29b-41d4-a716-446655440000
3996
- invalid_request_tier_targeting:
5523
+ custom_pixel_not_enabled:
3997
5524
  value:
3998
5525
  error:
3999
- code: invalid_request
4000
- message: 'tierTargeting is only allowed when strategyType is custom.'
5526
+ code: custom_pixel_not_enabled
5527
+ message: 'This organization does not have a custom Meta pixel enabled.'
4001
5528
  meta:
4002
5529
  requestId: 550e8400-e29b-41d4-a716-446655440000
4003
5530
 
4004
- CreateSoundlinkBadRequest:
5531
+ UpdatePixelBadRequest:
4005
5532
  description: |
4006
- Missing or malformed request body, or a missing/empty
4007
- `Idempotency-Key` header.
5533
+ Missing or malformed request body, unsupported platform, or the
5534
+ access token is already used with another pixel.
4008
5535
  content:
4009
5536
  application/json:
4010
5537
  schema:
4011
5538
  $ref: '#/components/schemas/ErrorResponse'
4012
5539
  examples:
4013
- missing_field:
5540
+ invalid_body:
4014
5541
  value:
4015
5542
  error:
4016
5543
  code: invalid_request
4017
- message: 'Missing required field: name.'
5544
+ message: 'Invalid request body at accessToken: Required.'
4018
5545
  meta:
4019
5546
  requestId: 550e8400-e29b-41d4-a716-446655440000
4020
- missing_idempotency_key:
5547
+ access_token_in_use:
4021
5548
  value:
4022
5549
  error:
4023
5550
  code: invalid_request
4024
- message: 'Idempotency-Key header is required and must not be empty.'
5551
+ message: 'Access token is already in use with another pixel ID'
4025
5552
  meta:
4026
5553
  requestId: 550e8400-e29b-41d4-a716-446655440000
4027
- pixel_pair:
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:
4028
5564
  value:
4029
5565
  error:
4030
- code: invalid_request
4031
- message: 'metaPixelId and metaConversionAccessToken must both be provided, or both omitted.'
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."
4032
5568
  meta:
4033
5569
  requestId: 550e8400-e29b-41d4-a716-446655440000
4034
5570
 
4035
- CreateSoundlinkForbidden:
5571
+ PixelTestEventBadRequest:
4036
5572
  description: |
4037
- Valid credentials but missing the `soundlinks:write` scope.
5573
+ Meta rejected the event because the pixel id or access token is wrong.
4038
5574
  content:
4039
5575
  application/json:
4040
5576
  schema:
4041
5577
  $ref: '#/components/schemas/ErrorResponse'
4042
5578
  examples:
4043
- insufficient_scope:
5579
+ meta_rejected:
4044
5580
  value:
4045
5581
  error:
4046
- code: insufficient_scope
4047
- message: 'This key does not have the soundlinks:write scope.'
5582
+ code: invalid_request
5583
+ message: 'Meta rejected the test event for pixel 1234567890123456. Check the pixel id and access token.'
4048
5584
  meta:
4049
5585
  requestId: 550e8400-e29b-41d4-a716-446655440000
4050
5586
 
4051
- CreateSoundlinkUnprocessable:
4052
- description: Request body is well-formed but the Spotify URL is invalid.
5587
+ InsufficientCredit:
5588
+ description: Wallet balance is too low to cover `dailyBudget * durationDays`
5589
+ content:
5590
+ application/json:
5591
+ schema:
5592
+ $ref: '#/components/schemas/ErrorResponse'
5593
+ example:
5594
+ error:
5595
+ code: insufficient_credit
5596
+ message: 'Insufficient wallet balance for this campaign.'
5597
+ details:
5598
+ available: 120.00
5599
+ required: 350.00
5600
+ meta:
5601
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5602
+
5603
+ CreateCampaignUnprocessable:
5604
+ description: Request body is well-formed but semantically invalid
4053
5605
  content:
4054
5606
  application/json:
4055
5607
  schema:
4056
5608
  $ref: '#/components/schemas/ErrorResponse'
4057
5609
  examples:
5610
+ invalid_genre:
5611
+ value:
5612
+ error:
5613
+ code: invalid_genre
5614
+ message: 'genre must be one of the supported values.'
5615
+ meta:
5616
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5617
+ invalid_duration_or_budget:
5618
+ value:
5619
+ error:
5620
+ code: invalid_duration_or_budget
5621
+ message: 'dailyBudget and durationDays must be greater than 0.'
5622
+ meta:
5623
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5624
+ invalid_daily_budget:
5625
+ value:
5626
+ error:
5627
+ code: invalid_daily_budget
5628
+ message: 'dailyBudget must be at least 10 (USD per day).'
5629
+ meta:
5630
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5631
+ invalid_duration_days:
5632
+ value:
5633
+ error:
5634
+ code: invalid_duration_days
5635
+ message: 'durationDays must be an integer from 7 to 30, or 60, or 90.'
5636
+ meta:
5637
+ requestId: 550e8400-e29b-41d4-a716-446655440000
4058
5638
  invalid_spotify_url:
4059
- summary: Malformed URL, unsupported type, or Spotify resource does not exist
5639
+ summary: Malformed URL or Spotify track/playlist does not exist
4060
5640
  value:
4061
5641
  error:
4062
5642
  code: invalid_spotify_url
4063
5643
  message: 'Spotify track not found.'
4064
5644
  meta:
4065
5645
  requestId: 550e8400-e29b-41d4-a716-446655440000
5646
+ invalid_tier_budget_allocation:
5647
+ value:
5648
+ error:
5649
+ code: invalid_tier_budget_allocation
5650
+ message: 'tierTargeting.customTiers[].percentBudget must sum to 100.'
5651
+ meta:
5652
+ requestId: 550e8400-e29b-41d4-a716-446655440000
5653
+ invalid_request_tier_targeting:
5654
+ value:
5655
+ error:
5656
+ code: invalid_request
5657
+ message: 'tierTargeting is only allowed when strategyType is custom.'
5658
+ meta:
5659
+ requestId: 550e8400-e29b-41d4-a716-446655440000
4066
5660
 
4067
5661
  IdempotencyKeyConflict:
4068
5662
  description: |
@@ -4088,18 +5682,20 @@ components:
4088
5682
  meta:
4089
5683
  requestId: 550e8400-e29b-41d4-a716-446655440000
4090
5684
 
4091
- TierUpdateCooldown:
5685
+ LearningEditAckRequired:
4092
5686
  description: |
4093
- Campaign tiers were updated in the last 72 hours. Wait for the cooldown
4094
- 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.
4095
5689
  content:
4096
5690
  application/json:
4097
5691
  schema:
4098
5692
  $ref: '#/components/schemas/ErrorResponse'
4099
5693
  example:
4100
5694
  error:
4101
- code: tier_update_cooldown
4102
- 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]
4103
5699
  meta:
4104
5700
  requestId: 550e8400-e29b-41d4-a716-446655440000
4105
5701