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