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.
- package/CHANGELOG.md +18 -0
- package/README.md +22 -1
- package/dist/cjs/index.cjs +95 -0
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +226 -10
- package/dist/esm/index.js +95 -0
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +2045 -449
- package/package.json +1 -1
|
@@ -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/
|
|
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
|
-
|
|
367
|
-
|
|
368
|
-
`
|
|
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
|
|
491
|
-
|
|
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,
|
|
543
|
-
|
|
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
|
-
**
|
|
598
|
-
|
|
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/
|
|
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,
|
|
663
|
-
streams, followers, and derived ratios.
|
|
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.
|
|
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.
|
|
1276
|
+
schemaVersion: '1.1'
|
|
759
1277
|
items:
|
|
760
1278
|
- provider: soundlink
|
|
761
1279
|
account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
762
|
-
schema_version: '1.
|
|
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.
|
|
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.
|
|
868
|
-
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.
|
|
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/
|
|
1588
|
+
/v1/campaigns/{campaignId}/metrics/retention:
|
|
1068
1589
|
get:
|
|
1069
|
-
operationId:
|
|
1070
|
-
summary:
|
|
1590
|
+
operationId: getCampaignRetention
|
|
1591
|
+
summary: Campaign cohort retention
|
|
1071
1592
|
description: |
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
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
|
|
1251
|
-
|
|
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}/
|
|
1294
|
-
|
|
1295
|
-
operationId:
|
|
1296
|
-
summary:
|
|
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
|
-
|
|
1299
|
-
|
|
1300
|
-
|
|
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
|
-
|
|
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:
|
|
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:
|
|
1969
|
+
description: Test event sent
|
|
1319
1970
|
content:
|
|
1320
1971
|
application/json:
|
|
1321
1972
|
schema:
|
|
1322
|
-
$ref: '#/components/schemas/
|
|
1973
|
+
$ref: '#/components/schemas/SendTestEventResponse'
|
|
1323
1974
|
example:
|
|
1324
1975
|
data:
|
|
1325
|
-
|
|
1326
|
-
|
|
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/
|
|
1987
|
+
/v1/soundlinks/{soundlinkId}/metrics/overview:
|
|
1342
1988
|
get:
|
|
1343
|
-
operationId:
|
|
1344
|
-
summary: Soundlink metrics
|
|
1989
|
+
operationId: getSoundlinkMetricsOverview
|
|
1990
|
+
summary: Soundlink metrics overview
|
|
1345
1991
|
description: |
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
|
|
1349
|
-
|
|
1350
|
-
|
|
1351
|
-
|
|
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:
|
|
2011
|
+
description: Soundlink totals
|
|
1385
2012
|
content:
|
|
1386
2013
|
application/json:
|
|
1387
2014
|
schema:
|
|
1388
|
-
$ref: '#/components/schemas/
|
|
2015
|
+
$ref: '#/components/schemas/SoundlinkMetricsOverviewResponse'
|
|
1389
2016
|
example:
|
|
1390
2017
|
data:
|
|
1391
|
-
|
|
1392
|
-
|
|
1393
|
-
|
|
1394
|
-
|
|
1395
|
-
|
|
1396
|
-
|
|
1397
|
-
|
|
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.
|
|
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
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
2748
|
+
WalletData:
|
|
2015
2749
|
type: object
|
|
2016
|
-
required: [
|
|
2750
|
+
required: [balance, available, reserved, currency, updatedAt]
|
|
2017
2751
|
properties:
|
|
2018
|
-
|
|
2019
|
-
type:
|
|
2020
|
-
|
|
2021
|
-
type:
|
|
2022
|
-
|
|
2023
|
-
type:
|
|
2024
|
-
|
|
2025
|
-
type:
|
|
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
|
-
|
|
2766
|
+
GetWalletResponse:
|
|
2028
2767
|
type: object
|
|
2029
|
-
required: [
|
|
2768
|
+
required: [data, meta]
|
|
2030
2769
|
properties:
|
|
2031
|
-
|
|
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
|
-
|
|
2034
|
-
|
|
2035
|
-
|
|
2036
|
-
|
|
2037
|
-
|
|
2038
|
-
|
|
2039
|
-
|
|
2040
|
-
|
|
2041
|
-
|
|
2042
|
-
|
|
2043
|
-
|
|
2044
|
-
|
|
2045
|
-
|
|
2046
|
-
|
|
2047
|
-
|
|
2048
|
-
|
|
2049
|
-
|
|
2050
|
-
|
|
2051
|
-
|
|
2052
|
-
|
|
2053
|
-
|
|
2054
|
-
|
|
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:
|
|
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:
|
|
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:
|
|
3714
|
+
minimum: 0
|
|
3715
|
+
exclusiveMinimum: true
|
|
2580
3716
|
description: |
|
|
2581
|
-
New daily budget in USD (gross). Must be at least
|
|
2582
|
-
lower than the campaign's current
|
|
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
|
|
2624
|
-
|
|
2625
|
-
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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
|
-
-
|
|
2702
|
-
-
|
|
2703
|
-
-
|
|
2704
|
-
-
|
|
2705
|
-
-
|
|
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
|
-
-
|
|
2715
|
-
- spend_media
|
|
2716
|
-
- spend_total
|
|
2717
|
-
- fees
|
|
2718
|
-
- currency
|
|
2719
|
-
- currency_account
|
|
3851
|
+
- link_clicks
|
|
2720
3852
|
- cpl
|
|
2721
3853
|
- cpf
|
|
2722
|
-
-
|
|
3854
|
+
- cpc_linkclick
|
|
3855
|
+
- frequency
|
|
2723
3856
|
properties:
|
|
2724
|
-
|
|
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
|
-
|
|
2731
|
-
|
|
3859
|
+
nullable: true
|
|
3860
|
+
language:
|
|
2732
3861
|
type: string
|
|
2733
|
-
|
|
2734
|
-
|
|
2735
|
-
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
3175
|
-
|
|
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
|
-
|
|
4648
|
+
SoundlinkCountryDailyRow:
|
|
3210
4649
|
type: object
|
|
3211
4650
|
description: |
|
|
3212
|
-
One row of the `
|
|
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
|
|
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
|
-
|
|
3290
|
-
|
|
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
|
|
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
|
|
3302
|
-
`new_listeners + returning_listeners`.
|
|
3303
|
-
the same listener can appear on
|
|
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
|
-
|
|
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 `
|
|
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/
|
|
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
|
-
|
|
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 `
|
|
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
|
-
|
|
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
|
-
-
|
|
3377
|
-
-
|
|
4842
|
+
- engaged_spotify_track_id
|
|
4843
|
+
- engaged_track_name
|
|
4844
|
+
- new_listeners
|
|
4845
|
+
- returning_listeners
|
|
3378
4846
|
- listeners
|
|
3379
|
-
-
|
|
3380
|
-
-
|
|
3381
|
-
|
|
3382
|
-
|
|
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
|
-
|
|
3433
|
-
|
|
3434
|
-
|
|
3435
|
-
link_clicks:
|
|
3436
|
-
type: integer
|
|
4909
|
+
example: US
|
|
4910
|
+
engaged_track_isrc:
|
|
4911
|
+
type: string
|
|
3437
4912
|
nullable: true
|
|
3438
4913
|
description: |
|
|
3439
|
-
|
|
3440
|
-
|
|
3441
|
-
|
|
3442
|
-
type:
|
|
3443
|
-
description:
|
|
3444
|
-
|
|
3445
|
-
|
|
3446
|
-
|
|
3447
|
-
|
|
3448
|
-
|
|
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
|
-
|
|
3452
|
-
|
|
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
|
-
|
|
3458
|
-
description: Unique listeners whose first play via this soundlink occurred on `report_date
|
|
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
|
-
|
|
3462
|
-
description: Unique listeners who played on `report_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
|
-
|
|
3466
|
-
description: Stream count from new listeners on `report_date
|
|
4946
|
+
minimum: 0
|
|
4947
|
+
description: Stream count from new listeners on `report_date`.
|
|
3467
4948
|
returning_listener_streams:
|
|
3468
4949
|
type: integer
|
|
3469
|
-
|
|
3470
|
-
description: Stream count from returning listeners on `report_date
|
|
3471
|
-
|
|
4950
|
+
minimum: 0
|
|
4951
|
+
description: Stream count from returning listeners on `report_date`.
|
|
4952
|
+
streams:
|
|
3472
4953
|
type: integer
|
|
3473
|
-
|
|
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
|
-
|
|
3482
|
-
|
|
3483
|
-
|
|
3484
|
-
|
|
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
|
-
|
|
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
|
|
4968
|
+
required: [schemaVersion, items]
|
|
3514
4969
|
properties:
|
|
3515
4970
|
schemaVersion:
|
|
3516
4971
|
type: string
|
|
3517
|
-
description: Version of the `
|
|
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/
|
|
3523
|
-
pagination:
|
|
3524
|
-
$ref: '#/components/schemas/Pagination'
|
|
4977
|
+
$ref: '#/components/schemas/SoundlinkCohortRetentionDailyRow'
|
|
3525
4978
|
meta:
|
|
3526
4979
|
$ref: '#/components/schemas/Meta'
|
|
3527
4980
|
|
|
3528
|
-
|
|
4981
|
+
SoundlinkCohortRetentionDailyRow:
|
|
3529
4982
|
type: object
|
|
3530
4983
|
description: |
|
|
3531
|
-
One row of the `
|
|
3532
|
-
Primary key: `(provider, account_id,
|
|
3533
|
-
Rows are idempotent
|
|
3534
|
-
|
|
3535
|
-
|
|
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
|
-
-
|
|
3543
|
-
-
|
|
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
|
-
-
|
|
3549
|
-
-
|
|
3550
|
-
-
|
|
3551
|
-
-
|
|
3552
|
-
-
|
|
3553
|
-
-
|
|
3554
|
-
-
|
|
3555
|
-
-
|
|
3556
|
-
-
|
|
3557
|
-
-
|
|
3558
|
-
-
|
|
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
|
-
|
|
5026
|
+
cohort_date:
|
|
3572
5027
|
type: string
|
|
3573
5028
|
format: date
|
|
3574
|
-
description: UTC calendar date
|
|
3575
|
-
|
|
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.
|
|
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.
|
|
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
|
-
|
|
3608
|
-
type:
|
|
3609
|
-
|
|
3610
|
-
description:
|
|
3611
|
-
|
|
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:
|
|
3635
|
-
description:
|
|
3636
|
-
|
|
3637
|
-
|
|
3638
|
-
|
|
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:
|
|
3642
|
-
|
|
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:
|
|
3646
|
-
|
|
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
|
-
|
|
3651
|
-
|
|
3652
|
-
|
|
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:
|
|
3656
|
-
|
|
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:
|
|
3660
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
3931
|
-
description:
|
|
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
|
-
|
|
3937
|
-
|
|
3938
|
-
|
|
3939
|
-
|
|
3940
|
-
|
|
3941
|
-
|
|
3942
|
-
|
|
3943
|
-
|
|
3944
|
-
|
|
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
|
-
|
|
3947
|
-
description:
|
|
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
|
-
|
|
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:
|
|
3964
|
-
message: '
|
|
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
|
-
|
|
5477
|
+
soundlink_plan_required:
|
|
3968
5478
|
value:
|
|
3969
5479
|
error:
|
|
3970
|
-
code:
|
|
3971
|
-
message: '
|
|
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
|
-
|
|
5484
|
+
attribution_not_enabled:
|
|
3975
5485
|
value:
|
|
3976
5486
|
error:
|
|
3977
|
-
code:
|
|
3978
|
-
message: '
|
|
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
|
|
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
|
-
|
|
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:
|
|
3993
|
-
message: '
|
|
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
|
-
|
|
5523
|
+
custom_pixel_not_enabled:
|
|
3997
5524
|
value:
|
|
3998
5525
|
error:
|
|
3999
|
-
code:
|
|
4000
|
-
message: '
|
|
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
|
-
|
|
5531
|
+
UpdatePixelBadRequest:
|
|
4005
5532
|
description: |
|
|
4006
|
-
Missing or malformed request body, or
|
|
4007
|
-
|
|
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
|
-
|
|
5540
|
+
invalid_body:
|
|
4014
5541
|
value:
|
|
4015
5542
|
error:
|
|
4016
5543
|
code: invalid_request
|
|
4017
|
-
message: '
|
|
5544
|
+
message: 'Invalid request body at accessToken: Required.'
|
|
4018
5545
|
meta:
|
|
4019
5546
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4020
|
-
|
|
5547
|
+
access_token_in_use:
|
|
4021
5548
|
value:
|
|
4022
5549
|
error:
|
|
4023
5550
|
code: invalid_request
|
|
4024
|
-
message: '
|
|
5551
|
+
message: 'Access token is already in use with another pixel ID'
|
|
4025
5552
|
meta:
|
|
4026
5553
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
4027
|
-
|
|
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:
|
|
4031
|
-
message: '
|
|
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
|
-
|
|
5571
|
+
PixelTestEventBadRequest:
|
|
4036
5572
|
description: |
|
|
4037
|
-
|
|
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
|
-
|
|
5579
|
+
meta_rejected:
|
|
4044
5580
|
value:
|
|
4045
5581
|
error:
|
|
4046
|
-
code:
|
|
4047
|
-
message: '
|
|
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
|
-
|
|
4052
|
-
description:
|
|
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
|
|
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
|
-
|
|
5685
|
+
LearningEditAckRequired:
|
|
4092
5686
|
description: |
|
|
4093
|
-
|
|
4094
|
-
|
|
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:
|
|
4102
|
-
message: '
|
|
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
|
|