soundlink 2.0.0 → 2.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +17 -0
- package/README.md +34 -1
- package/dist/cjs/index.cjs +162 -4
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/esm/index.d.ts +267 -5
- package/dist/esm/index.js +162 -5
- package/dist/esm/index.js.map +1 -1
- package/openapi/soundlink-public-api-v1.yaml +2379 -875
- package/package.json +2 -1
|
@@ -7,19 +7,43 @@ info:
|
|
|
7
7
|
|
|
8
8
|
**Base URL:** `https://api.getsoundlink.com`
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
## Authentication
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Send `Authorization: Bearer` with one of:
|
|
13
|
+
|
|
14
|
+
1. **API key (recommended)** — a `sk_*` key from the Soundlink app
|
|
15
|
+
(Settings → Developer → API keys):
|
|
13
16
|
```
|
|
14
17
|
Authorization: Bearer sk_abc123_<token>
|
|
15
18
|
```
|
|
16
19
|
|
|
17
|
-
2.
|
|
20
|
+
2. **OAuth Bearer** — an access token from Sign in with Soundlink
|
|
21
|
+
(authorization code or client credentials). Token scopes use the
|
|
22
|
+
same strings as Public API key scopes (for example `campaigns:read`,
|
|
23
|
+
`metrics:read`):
|
|
18
24
|
```
|
|
19
|
-
|
|
25
|
+
Authorization: Bearer <oauth_access_token>
|
|
20
26
|
```
|
|
21
27
|
|
|
22
|
-
|
|
28
|
+
`x-api-key` is no longer accepted and is ignored if sent. Requests
|
|
29
|
+
without `Authorization: Bearer` return `401 invalid_api_key` (or
|
|
30
|
+
`401 invalid_token` when a Bearer value is present but neither a
|
|
31
|
+
recognized `sk_*` key nor a valid OAuth access token).
|
|
32
|
+
|
|
33
|
+
### Which operations accept OAuth?
|
|
34
|
+
|
|
35
|
+
| Operations | Required scope | Auth |
|
|
36
|
+
| --- | --- | --- |
|
|
37
|
+
| `GET /v1/ping` | any granted Public API scope | API key (Bearer) or OAuth Bearer |
|
|
38
|
+
| Campaign reads (`GET /v1/strategies`, `GET /v1/campaigns`, campaign detail, tiers) | `campaigns:read` | API key (Bearer) or OAuth Bearer |
|
|
39
|
+
| Metrics reads (overview, breakdown, exports) | `metrics:read` | API key (Bearer) or OAuth Bearer |
|
|
40
|
+
| Campaign writes (create, stop, budget, tier updates) | `campaigns:write` | API key (Bearer) or OAuth Bearer |
|
|
41
|
+
| Video import / import status | `videos:write` | API key (Bearer) or OAuth Bearer |
|
|
42
|
+
| Soundlink reads (list, detail, metrics overview/timeseries/breakdown/engagement, JSONL exports) | `soundlinks:read` | API key (Bearer) or OAuth Bearer |
|
|
43
|
+
|
|
44
|
+
Per-operation scope requirements are also marked with `x-required-scope`
|
|
45
|
+
(except `GET /v1/ping`, which accepts any valid credential with at least
|
|
46
|
+
one Public API scope granted to the key/token).
|
|
23
47
|
|
|
24
48
|
All responses are wrapped in a standard envelope:
|
|
25
49
|
```json
|
|
@@ -33,8 +57,8 @@ servers:
|
|
|
33
57
|
description: Production
|
|
34
58
|
|
|
35
59
|
security:
|
|
36
|
-
- apiKeyAuth: []
|
|
37
60
|
- apiKeyBearerAuth: []
|
|
61
|
+
- oauthBearer: []
|
|
38
62
|
|
|
39
63
|
tags:
|
|
40
64
|
- name: System
|
|
@@ -45,6 +69,8 @@ tags:
|
|
|
45
69
|
description: Campaign performance metrics
|
|
46
70
|
- name: Videos
|
|
47
71
|
description: Partner video library import for Full Control campaigns
|
|
72
|
+
- name: Soundlinks
|
|
73
|
+
description: Soundlink listing, detail, and performance metrics
|
|
48
74
|
|
|
49
75
|
paths:
|
|
50
76
|
/v1/ping:
|
|
@@ -53,12 +79,13 @@ paths:
|
|
|
53
79
|
summary: Verify connectivity and authentication
|
|
54
80
|
description: |
|
|
55
81
|
Returns `{ "status": "ok" }` if the request is authenticated and the
|
|
56
|
-
API is reachable. Useful for verifying a newly issued key
|
|
57
|
-
data requests.
|
|
82
|
+
API is reachable. Useful for verifying a newly issued API key or OAuth
|
|
83
|
+
access token before making data requests. Accepts either credential;
|
|
84
|
+
no specific scope is required beyond a valid key/token.
|
|
58
85
|
tags: [System]
|
|
59
86
|
security:
|
|
60
|
-
- apiKeyAuth: []
|
|
61
87
|
- apiKeyBearerAuth: []
|
|
88
|
+
- oauthBearer: []
|
|
62
89
|
responses:
|
|
63
90
|
'200':
|
|
64
91
|
description: Authenticated and reachable
|
|
@@ -95,11 +122,11 @@ paths:
|
|
|
95
122
|
`POST /v1/campaigns`. Built-in strategies apply platform default
|
|
96
123
|
tiering internally; only `custom` allows `tierTargeting` on create.
|
|
97
124
|
|
|
98
|
-
Requires the `campaigns:read` scope.
|
|
125
|
+
Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
|
|
99
126
|
tags: [Campaigns]
|
|
100
127
|
security:
|
|
101
|
-
- apiKeyAuth: []
|
|
102
128
|
- apiKeyBearerAuth: []
|
|
129
|
+
- oauthBearer: []
|
|
103
130
|
x-required-scope: campaigns:read
|
|
104
131
|
responses:
|
|
105
132
|
'200':
|
|
@@ -133,10 +160,13 @@ paths:
|
|
|
133
160
|
description: |
|
|
134
161
|
Returns all campaigns for the authenticated organization.
|
|
135
162
|
Intended for reporting and data warehouse sync.
|
|
163
|
+
|
|
164
|
+
Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
|
|
136
165
|
tags: [Campaigns]
|
|
137
166
|
security:
|
|
138
|
-
- apiKeyAuth: []
|
|
139
167
|
- apiKeyBearerAuth: []
|
|
168
|
+
- oauthBearer: []
|
|
169
|
+
x-required-scope: campaigns:read
|
|
140
170
|
parameters:
|
|
141
171
|
- $ref: '#/components/parameters/page'
|
|
142
172
|
- $ref: '#/components/parameters/pageSize100'
|
|
@@ -190,10 +220,12 @@ paths:
|
|
|
190
220
|
deducted from the wallet balance), so the `Idempotency-Key` header
|
|
191
221
|
is **required** on every request. See the header description below
|
|
192
222
|
for retry semantics.
|
|
223
|
+
|
|
224
|
+
**Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
|
|
193
225
|
tags: [Campaigns]
|
|
194
226
|
security:
|
|
195
|
-
- apiKeyAuth: []
|
|
196
227
|
- apiKeyBearerAuth: []
|
|
228
|
+
- oauthBearer: []
|
|
197
229
|
x-required-scope: campaigns:write
|
|
198
230
|
parameters:
|
|
199
231
|
- $ref: '#/components/parameters/idempotencyKey'
|
|
@@ -283,11 +315,15 @@ paths:
|
|
|
283
315
|
get:
|
|
284
316
|
operationId: getCampaign
|
|
285
317
|
summary: Get campaign
|
|
286
|
-
description:
|
|
318
|
+
description: |
|
|
319
|
+
Fetch full details for a single campaign.
|
|
320
|
+
|
|
321
|
+
Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
|
|
287
322
|
tags: [Campaigns]
|
|
288
323
|
security:
|
|
289
|
-
- apiKeyAuth: []
|
|
290
324
|
- apiKeyBearerAuth: []
|
|
325
|
+
- oauthBearer: []
|
|
326
|
+
x-required-scope: campaigns:read
|
|
291
327
|
parameters:
|
|
292
328
|
- $ref: '#/components/parameters/campaignId'
|
|
293
329
|
responses:
|
|
@@ -331,11 +367,13 @@ paths:
|
|
|
331
367
|
already-stopped campaign succeeds without double-refunding. The
|
|
332
368
|
`Idempotency-Key` header is also **required** so retries of the same
|
|
333
369
|
request replay the original response without repeating side effects.
|
|
370
|
+
|
|
371
|
+
**Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
|
|
334
372
|
tags: [Campaigns]
|
|
335
373
|
x-required-scope: campaigns:write
|
|
336
374
|
security:
|
|
337
|
-
- apiKeyAuth: []
|
|
338
375
|
- apiKeyBearerAuth: []
|
|
376
|
+
- oauthBearer: []
|
|
339
377
|
parameters:
|
|
340
378
|
- $ref: '#/components/parameters/campaignId'
|
|
341
379
|
- $ref: '#/components/parameters/idempotencyKey'
|
|
@@ -377,11 +415,13 @@ paths:
|
|
|
377
415
|
- `current_and_renewals` — applies to the current cycle and future renewals
|
|
378
416
|
|
|
379
417
|
Debits the organization wallet when the current cycle is increased.
|
|
418
|
+
|
|
419
|
+
**Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
|
|
380
420
|
tags: [Campaigns]
|
|
381
421
|
x-required-scope: campaigns:write
|
|
382
422
|
security:
|
|
383
|
-
- apiKeyAuth: []
|
|
384
423
|
- apiKeyBearerAuth: []
|
|
424
|
+
- oauthBearer: []
|
|
385
425
|
parameters:
|
|
386
426
|
- $ref: '#/components/parameters/campaignId'
|
|
387
427
|
- $ref: '#/components/parameters/idempotencyKey'
|
|
@@ -450,11 +490,13 @@ paths:
|
|
|
450
490
|
- `targetDailyBudget` must be at least `$10`/day and lower than the
|
|
451
491
|
current daily budget
|
|
452
492
|
- more than 3 days must remain in the current cycle
|
|
493
|
+
|
|
494
|
+
**Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
|
|
453
495
|
tags: [Campaigns]
|
|
454
496
|
x-required-scope: campaigns:write
|
|
455
497
|
security:
|
|
456
|
-
- apiKeyAuth: []
|
|
457
498
|
- apiKeyBearerAuth: []
|
|
499
|
+
- oauthBearer: []
|
|
458
500
|
parameters:
|
|
459
501
|
- $ref: '#/components/parameters/campaignId'
|
|
460
502
|
- $ref: '#/components/parameters/idempotencyKey'
|
|
@@ -501,11 +543,13 @@ paths:
|
|
|
501
543
|
updated (`lastUpdate`). Use this before `PATCH` to build a valid request.
|
|
502
544
|
|
|
503
545
|
**Wallet campaigns only** (`generation: 3`).
|
|
546
|
+
|
|
547
|
+
Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
|
|
504
548
|
tags: [Campaigns]
|
|
505
549
|
x-required-scope: campaigns:read
|
|
506
550
|
security:
|
|
507
|
-
- apiKeyAuth: []
|
|
508
551
|
- apiKeyBearerAuth: []
|
|
552
|
+
- oauthBearer: []
|
|
509
553
|
parameters:
|
|
510
554
|
- $ref: '#/components/parameters/campaignId'
|
|
511
555
|
responses:
|
|
@@ -552,11 +596,13 @@ paths:
|
|
|
552
596
|
|
|
553
597
|
**Cooldown:** after a successful update, further tier changes are
|
|
554
598
|
blocked for **72 hours** (`409 tier_update_cooldown`).
|
|
599
|
+
|
|
600
|
+
**Auth:** Accepts API key or OAuth Bearer (`campaigns:write`).
|
|
555
601
|
tags: [Campaigns]
|
|
556
602
|
x-required-scope: campaigns:write
|
|
557
603
|
security:
|
|
558
|
-
- apiKeyAuth: []
|
|
559
604
|
- apiKeyBearerAuth: []
|
|
605
|
+
- oauthBearer: []
|
|
560
606
|
parameters:
|
|
561
607
|
- $ref: '#/components/parameters/campaignId'
|
|
562
608
|
requestBody:
|
|
@@ -618,10 +664,13 @@ paths:
|
|
|
618
664
|
`/metrics/breakdown` for those.
|
|
619
665
|
|
|
620
666
|
Suitable for dashboards and quick syncs.
|
|
667
|
+
|
|
668
|
+
Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
|
|
621
669
|
tags: [Metrics]
|
|
622
670
|
security:
|
|
623
|
-
- apiKeyAuth: []
|
|
624
671
|
- apiKeyBearerAuth: []
|
|
672
|
+
- oauthBearer: []
|
|
673
|
+
x-required-scope: metrics:read
|
|
625
674
|
parameters:
|
|
626
675
|
- $ref: '#/components/parameters/campaignId'
|
|
627
676
|
- $ref: '#/components/parameters/startDate'
|
|
@@ -677,10 +726,13 @@ paths:
|
|
|
677
726
|
|
|
678
727
|
Maps to the **Countries** tab in the Soundlink Insights UI.
|
|
679
728
|
Use for daily warehouse loads.
|
|
729
|
+
|
|
730
|
+
Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
|
|
680
731
|
tags: [Metrics]
|
|
681
732
|
security:
|
|
682
|
-
- apiKeyAuth: []
|
|
683
733
|
- apiKeyBearerAuth: []
|
|
734
|
+
- oauthBearer: []
|
|
735
|
+
x-required-scope: metrics:read
|
|
684
736
|
parameters:
|
|
685
737
|
- $ref: '#/components/parameters/campaignId'
|
|
686
738
|
- $ref: '#/components/parameters/startDate'
|
|
@@ -780,10 +832,13 @@ paths:
|
|
|
780
832
|
to 7 days after the date closes due to delayed events from Meta and
|
|
781
833
|
Spotify. Re-fetching and re-ingesting on the primary key is safe
|
|
782
834
|
(idempotent).
|
|
835
|
+
|
|
836
|
+
Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
|
|
783
837
|
tags: [Metrics]
|
|
784
838
|
security:
|
|
785
|
-
- apiKeyAuth: []
|
|
786
839
|
- apiKeyBearerAuth: []
|
|
840
|
+
- oauthBearer: []
|
|
841
|
+
x-required-scope: metrics:read
|
|
787
842
|
parameters:
|
|
788
843
|
- $ref: '#/components/parameters/campaignId'
|
|
789
844
|
- $ref: '#/components/parameters/startDate'
|
|
@@ -818,6 +873,116 @@ paths:
|
|
|
818
873
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
819
874
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
820
875
|
|
|
876
|
+
/v1/campaigns/{campaignId}/metrics/engagement:
|
|
877
|
+
get:
|
|
878
|
+
operationId: getCampaignEngagement
|
|
879
|
+
summary: Campaign engagement breakdown
|
|
880
|
+
description: |
|
|
881
|
+
Per-day, per-track engagement metrics for a campaign. One row per
|
|
882
|
+
`(report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
883
|
+
Results are paginated.
|
|
884
|
+
|
|
885
|
+
**Row schema:** `campaign_engagement_daily` v1.0 — the same schema used
|
|
886
|
+
in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting
|
|
887
|
+
is safe.
|
|
888
|
+
|
|
889
|
+
**Key difference from `/metrics/breakdown`:** this endpoint covers the
|
|
890
|
+
full engagement window — including post-campaign streaming activity —
|
|
891
|
+
not just dates when the campaign was actively running.
|
|
892
|
+
|
|
893
|
+
**`engagement_context` values:**
|
|
894
|
+
- `catalog` — same-artist spillover (and direct promoted-track plays)
|
|
895
|
+
on track campaigns.
|
|
896
|
+
- `playlist` — per-track performance inside the promoted playlist on
|
|
897
|
+
playlist campaigns.
|
|
898
|
+
|
|
899
|
+
**`listeners` is deduplicated within each row only.** Do not sum
|
|
900
|
+
`listeners` across days to get a campaign total.
|
|
901
|
+
|
|
902
|
+
**Date range:** if you omit both dates, defaults to the last **90 days**
|
|
903
|
+
ending today. Override with `startDate` / `endDate`. **Responses are
|
|
904
|
+
capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
|
|
905
|
+
|
|
906
|
+
**Mutability window:** rows for a given `report_date` can be revised
|
|
907
|
+
for up to 7 days after the date closes due to delayed Spotify
|
|
908
|
+
playback events.
|
|
909
|
+
|
|
910
|
+
Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
|
|
911
|
+
tags: [Metrics]
|
|
912
|
+
security:
|
|
913
|
+
- apiKeyBearerAuth: []
|
|
914
|
+
- oauthBearer: []
|
|
915
|
+
x-required-scope: metrics:read
|
|
916
|
+
parameters:
|
|
917
|
+
- $ref: '#/components/parameters/campaignId'
|
|
918
|
+
- $ref: '#/components/parameters/startDate'
|
|
919
|
+
- $ref: '#/components/parameters/endDate'
|
|
920
|
+
- name: engagementContext
|
|
921
|
+
in: query
|
|
922
|
+
schema:
|
|
923
|
+
type: string
|
|
924
|
+
enum: [catalog, playlist]
|
|
925
|
+
description: Filter to a single engagement context. Omit to return both.
|
|
926
|
+
- $ref: '#/components/parameters/page'
|
|
927
|
+
- $ref: '#/components/parameters/pageSize500'
|
|
928
|
+
- name: sortBy
|
|
929
|
+
in: query
|
|
930
|
+
schema:
|
|
931
|
+
type: string
|
|
932
|
+
enum: [report_date]
|
|
933
|
+
default: report_date
|
|
934
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
935
|
+
responses:
|
|
936
|
+
'200':
|
|
937
|
+
description: Paginated engagement rows (`campaign_engagement_daily` schema)
|
|
938
|
+
content:
|
|
939
|
+
application/json:
|
|
940
|
+
schema:
|
|
941
|
+
$ref: '#/components/schemas/MetricsEngagementResponse'
|
|
942
|
+
example:
|
|
943
|
+
data:
|
|
944
|
+
schemaVersion: '1.0'
|
|
945
|
+
items:
|
|
946
|
+
- provider: soundlink
|
|
947
|
+
account_id: a7ac3173-2f71-4e79-921f-d15d7112cc9a
|
|
948
|
+
schema_version: '1.0'
|
|
949
|
+
report_date: '2026-04-08'
|
|
950
|
+
report_date_timezone: UTC
|
|
951
|
+
exported_at: '2026-05-22T10:12:11Z'
|
|
952
|
+
campaign_id: 8ccd7b88-2591-4b94-848f-f142f5c6bba1
|
|
953
|
+
campaign_name: 9 To 5
|
|
954
|
+
campaign_target_type: track
|
|
955
|
+
campaign_target_isrc: DEXW62500272
|
|
956
|
+
campaign_target_spotify_track_id: 2RkZ5WPkKyBf0u8vN3dNgb
|
|
957
|
+
campaign_target_playlist_id: null
|
|
958
|
+
status: ended
|
|
959
|
+
engagement_context: catalog
|
|
960
|
+
country_code: US
|
|
961
|
+
engaged_track_isrc: DEXW62500001
|
|
962
|
+
engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
|
|
963
|
+
engaged_track_name: Till The Sunrise
|
|
964
|
+
playlist_position: null
|
|
965
|
+
new_listeners: 42
|
|
966
|
+
returning_listeners: 18
|
|
967
|
+
listeners: 60
|
|
968
|
+
new_listener_streams: 58
|
|
969
|
+
returning_listener_streams: 31
|
|
970
|
+
streams: 89
|
|
971
|
+
spl: 1.48
|
|
972
|
+
pagination:
|
|
973
|
+
page: 1
|
|
974
|
+
pageSize: 50
|
|
975
|
+
totalCount: 120
|
|
976
|
+
totalPages: 3
|
|
977
|
+
meta:
|
|
978
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
979
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
980
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
981
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
982
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
983
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
984
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
985
|
+
|
|
821
986
|
/v1/campaigns/{campaignId}/metrics/engagement/export:
|
|
822
987
|
get:
|
|
823
988
|
operationId: exportCampaignEngagement
|
|
@@ -825,7 +990,9 @@ paths:
|
|
|
825
990
|
description: |
|
|
826
991
|
Streams the full engagement dataset for a campaign as
|
|
827
992
|
**newline-delimited JSON (JSONL)**. Every line is a complete, valid
|
|
828
|
-
JSON object conforming to the `campaign_engagement_daily` v1.0 schema
|
|
993
|
+
JSON object conforming to the `campaign_engagement_daily` v1.0 schema
|
|
994
|
+
— identical to the rows returned by `GET /metrics/engagement` but
|
|
995
|
+
without pagination or an envelope wrapper.
|
|
829
996
|
|
|
830
997
|
Designed for data pipeline consumers: load directly into BigQuery,
|
|
831
998
|
Snowflake, or any JSONL-aware ingest tool without cursor logic.
|
|
@@ -850,10 +1017,13 @@ paths:
|
|
|
850
1017
|
**Mutability:** rows for a given `report_date` can be revised for up to
|
|
851
1018
|
7 days after the date closes. Re-fetching and re-ingesting on the
|
|
852
1019
|
primary key is safe (idempotent).
|
|
1020
|
+
|
|
1021
|
+
Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
|
|
853
1022
|
tags: [Metrics]
|
|
854
1023
|
security:
|
|
855
|
-
- apiKeyAuth: []
|
|
856
1024
|
- apiKeyBearerAuth: []
|
|
1025
|
+
- oauthBearer: []
|
|
1026
|
+
x-required-scope: metrics:read
|
|
857
1027
|
parameters:
|
|
858
1028
|
- $ref: '#/components/parameters/campaignId'
|
|
859
1029
|
- $ref: '#/components/parameters/startDate'
|
|
@@ -894,885 +1064,2148 @@ paths:
|
|
|
894
1064
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
895
1065
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
896
1066
|
|
|
897
|
-
/v1/
|
|
898
|
-
|
|
899
|
-
operationId:
|
|
900
|
-
summary:
|
|
1067
|
+
/v1/soundlinks:
|
|
1068
|
+
get:
|
|
1069
|
+
operationId: listSoundlinks
|
|
1070
|
+
summary: List soundlinks
|
|
901
1071
|
description: |
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
(content duplicate).
|
|
1072
|
+
Returns the organization's self-serve soundlinks. Soundlinks linked
|
|
1073
|
+
to a campaign are the campaign's underlying resource and are served
|
|
1074
|
+
by the Campaigns endpoints instead.
|
|
906
1075
|
|
|
907
|
-
|
|
908
|
-
|
|
1076
|
+
Soundlink schemas contain no financial fields: ads for self-serve
|
|
1077
|
+
soundlinks run in your own Meta account, so spend is not visible to
|
|
1078
|
+
Soundlink.
|
|
909
1079
|
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
tags: [Videos]
|
|
1080
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1081
|
+
tags: [Soundlinks]
|
|
913
1082
|
security:
|
|
914
|
-
- apiKeyAuth: []
|
|
915
1083
|
- apiKeyBearerAuth: []
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
1084
|
+
- oauthBearer: []
|
|
1085
|
+
x-required-scope: soundlinks:read
|
|
1086
|
+
parameters:
|
|
1087
|
+
- $ref: '#/components/parameters/page'
|
|
1088
|
+
- $ref: '#/components/parameters/pageSize100'
|
|
1089
|
+
- name: sortBy
|
|
1090
|
+
in: query
|
|
1091
|
+
schema:
|
|
1092
|
+
type: string
|
|
1093
|
+
enum: [createdAt]
|
|
1094
|
+
default: createdAt
|
|
1095
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
925
1096
|
responses:
|
|
926
1097
|
'200':
|
|
927
|
-
description:
|
|
1098
|
+
description: Paginated list of soundlinks
|
|
928
1099
|
content:
|
|
929
1100
|
application/json:
|
|
930
1101
|
schema:
|
|
931
|
-
$ref: '#/components/schemas/
|
|
932
|
-
|
|
933
|
-
|
|
1102
|
+
$ref: '#/components/schemas/SoundlinkListResponse'
|
|
1103
|
+
example:
|
|
1104
|
+
data:
|
|
1105
|
+
items:
|
|
1106
|
+
- soundlinkId: V1StGXR8_Z5jdHi6B-myT
|
|
1107
|
+
organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1108
|
+
name: Midnight Drive
|
|
1109
|
+
url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
|
|
1110
|
+
targetType: track
|
|
1111
|
+
spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
|
|
1112
|
+
status: active
|
|
1113
|
+
createdAt: '2026-04-01T10:00:00Z'
|
|
1114
|
+
pagination:
|
|
1115
|
+
page: 1
|
|
1116
|
+
pageSize: 10
|
|
1117
|
+
totalCount: 42
|
|
1118
|
+
totalPages: 5
|
|
1119
|
+
meta:
|
|
1120
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1121
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1122
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1123
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1124
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1125
|
+
|
|
1126
|
+
/v1/soundlinks/{soundlinkId}:
|
|
1127
|
+
get:
|
|
1128
|
+
operationId: getSoundlink
|
|
1129
|
+
summary: Get soundlink
|
|
1130
|
+
description: |
|
|
1131
|
+
Fetch details for a single self-serve soundlink. Soundlinks linked
|
|
1132
|
+
to a campaign are not addressable here and return `404`.
|
|
1133
|
+
|
|
1134
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1135
|
+
tags: [Soundlinks]
|
|
1136
|
+
security:
|
|
1137
|
+
- apiKeyBearerAuth: []
|
|
1138
|
+
- oauthBearer: []
|
|
1139
|
+
x-required-scope: soundlinks:read
|
|
1140
|
+
parameters:
|
|
1141
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1142
|
+
responses:
|
|
1143
|
+
'200':
|
|
1144
|
+
description: Soundlink detail
|
|
934
1145
|
content:
|
|
935
1146
|
application/json:
|
|
936
1147
|
schema:
|
|
937
|
-
$ref: '#/components/schemas/
|
|
1148
|
+
$ref: '#/components/schemas/SoundlinkDetailResponse'
|
|
1149
|
+
example:
|
|
1150
|
+
data:
|
|
1151
|
+
soundlinkId: V1StGXR8_Z5jdHi6B-myT
|
|
1152
|
+
organizationId: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1153
|
+
name: Midnight Drive
|
|
1154
|
+
url: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
|
|
1155
|
+
targetType: track
|
|
1156
|
+
spotifyUrl: https://open.spotify.com/track/11dFghVXANMlKmJXsNCbNl
|
|
1157
|
+
status: active
|
|
1158
|
+
createdAt: '2026-04-01T10:00:00Z'
|
|
1159
|
+
autoFollow: true
|
|
1160
|
+
metaPixelId: '1234567890123456'
|
|
1161
|
+
tiktokPixelId: null
|
|
1162
|
+
meta:
|
|
1163
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1164
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1165
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1166
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1167
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1168
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1169
|
+
|
|
1170
|
+
/v1/soundlinks/{soundlinkId}/metrics/overview:
|
|
1171
|
+
get:
|
|
1172
|
+
operationId: getSoundlinkMetricsOverview
|
|
1173
|
+
summary: Soundlink metrics overview
|
|
1174
|
+
description: |
|
|
1175
|
+
Soundlink-level totals for a date range: landing page views, outbound
|
|
1176
|
+
clicks, listeners, streams, followers, and derived ratios. Totals are
|
|
1177
|
+
sums of country-day mart rows (`api_smart_link_country_daily`);
|
|
1178
|
+
`listeners` is the sum of daily country `new_listeners` (not
|
|
1179
|
+
period-unique). No per-day rows — use `/metrics/timeseries` for those,
|
|
1180
|
+
or `/metrics/breakdown` for country-day rows (including new/returning
|
|
1181
|
+
splits).
|
|
1182
|
+
|
|
1183
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1184
|
+
tags: [Soundlinks]
|
|
1185
|
+
security:
|
|
1186
|
+
- apiKeyBearerAuth: []
|
|
1187
|
+
- oauthBearer: []
|
|
1188
|
+
x-required-scope: soundlinks:read
|
|
1189
|
+
parameters:
|
|
1190
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1191
|
+
- $ref: '#/components/parameters/soundlinkStartDate'
|
|
1192
|
+
- $ref: '#/components/parameters/soundlinkEndDate'
|
|
1193
|
+
responses:
|
|
1194
|
+
'200':
|
|
1195
|
+
description: Soundlink totals
|
|
1196
|
+
content:
|
|
1197
|
+
application/json:
|
|
1198
|
+
schema:
|
|
1199
|
+
$ref: '#/components/schemas/SoundlinkMetricsOverviewResponse'
|
|
1200
|
+
example:
|
|
1201
|
+
data:
|
|
1202
|
+
views: 4821
|
|
1203
|
+
link_clicks: 890
|
|
1204
|
+
streams: 9340
|
|
1205
|
+
listeners: 3980
|
|
1206
|
+
followers: 312
|
|
1207
|
+
streams_per_listener: 2.35
|
|
1208
|
+
ctr_lp: 0.185
|
|
1209
|
+
meta:
|
|
1210
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
938
1211
|
'400': { $ref: '#/components/responses/BadRequest' }
|
|
939
1212
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
940
1213
|
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1214
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
941
1215
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
942
1216
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
943
1217
|
|
|
944
|
-
/v1/
|
|
1218
|
+
/v1/soundlinks/{soundlinkId}/metrics/timeseries:
|
|
945
1219
|
get:
|
|
946
|
-
operationId:
|
|
947
|
-
summary:
|
|
1220
|
+
operationId: getSoundlinkMetricsTimeseries
|
|
1221
|
+
summary: Soundlink metrics timeseries
|
|
948
1222
|
description: |
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
1223
|
+
Per-day metrics for a soundlink. One row per `report_date`. Results
|
|
1224
|
+
are paginated.
|
|
1225
|
+
|
|
1226
|
+
**Row schema:** `soundlink_daily` v1.0. Rows are idempotent on the
|
|
1227
|
+
primary key `(provider, account_id, report_date, soundlink_id)`;
|
|
1228
|
+
re-ingesting is safe.
|
|
1229
|
+
|
|
1230
|
+
**Mutability window:** rows for a given `report_date` can be revised
|
|
1231
|
+
for up to 7 days after the date closes due to delayed Spotify playback
|
|
1232
|
+
events. Re-fetch or re-ingest accordingly.
|
|
1233
|
+
|
|
1234
|
+
Rows are aggregated across countries (no `country_code`) and
|
|
1235
|
+
contain no financial fields. For country-day rows use
|
|
1236
|
+
`/metrics/breakdown` (and `/metrics/breakdown/export`).
|
|
1237
|
+
|
|
1238
|
+
Maps to the **Trends** tab in the Soundlink Insights UI.
|
|
1239
|
+
|
|
1240
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1241
|
+
tags: [Soundlinks]
|
|
952
1242
|
security:
|
|
953
|
-
- apiKeyAuth: []
|
|
954
1243
|
- apiKeyBearerAuth: []
|
|
955
|
-
|
|
1244
|
+
- oauthBearer: []
|
|
1245
|
+
x-required-scope: soundlinks:read
|
|
956
1246
|
parameters:
|
|
957
|
-
-
|
|
958
|
-
|
|
959
|
-
|
|
1247
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1248
|
+
- $ref: '#/components/parameters/soundlinkStartDate'
|
|
1249
|
+
- $ref: '#/components/parameters/soundlinkEndDate'
|
|
1250
|
+
- $ref: '#/components/parameters/page'
|
|
1251
|
+
- $ref: '#/components/parameters/pageSize500'
|
|
1252
|
+
- name: sortBy
|
|
1253
|
+
in: query
|
|
960
1254
|
schema:
|
|
961
1255
|
type: string
|
|
962
|
-
|
|
963
|
-
|
|
1256
|
+
enum: [report_date]
|
|
1257
|
+
default: report_date
|
|
1258
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
964
1259
|
responses:
|
|
965
1260
|
'200':
|
|
966
|
-
description:
|
|
1261
|
+
description: Paginated per-day rows (`soundlink_daily` schema)
|
|
967
1262
|
content:
|
|
968
1263
|
application/json:
|
|
969
1264
|
schema:
|
|
970
|
-
$ref: '#/components/schemas/
|
|
1265
|
+
$ref: '#/components/schemas/SoundlinkTimeseriesResponse'
|
|
1266
|
+
example:
|
|
1267
|
+
data:
|
|
1268
|
+
schemaVersion: '1.0'
|
|
1269
|
+
items:
|
|
1270
|
+
- provider: soundlink
|
|
1271
|
+
account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1272
|
+
schema_version: '1.0'
|
|
1273
|
+
report_date: '2026-08-01'
|
|
1274
|
+
report_date_timezone: UTC
|
|
1275
|
+
exported_at: '2026-08-28T03:00:00Z'
|
|
1276
|
+
soundlink_id: V1StGXR8_Z5jdHi6B-myT
|
|
1277
|
+
soundlink_name: Midnight Drive
|
|
1278
|
+
soundlink_target_type: track
|
|
1279
|
+
soundlink_target_isrc: DEXW62500259
|
|
1280
|
+
soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
1281
|
+
soundlink_target_playlist_id: null
|
|
1282
|
+
views: 4821
|
|
1283
|
+
link_clicks: 890
|
|
1284
|
+
streams: 203
|
|
1285
|
+
listeners: 145
|
|
1286
|
+
new_listeners: 120
|
|
1287
|
+
returning_listeners: 25
|
|
1288
|
+
new_listener_streams: 160
|
|
1289
|
+
returning_listener_streams: 43
|
|
1290
|
+
followers: 12
|
|
1291
|
+
streams_per_listener: 1.4
|
|
1292
|
+
ctr_lp: 0.185
|
|
1293
|
+
pagination:
|
|
1294
|
+
page: 1
|
|
1295
|
+
pageSize: 50
|
|
1296
|
+
totalCount: 90
|
|
1297
|
+
totalPages: 2
|
|
1298
|
+
meta:
|
|
1299
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1300
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
971
1301
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
972
1302
|
'403': { $ref: '#/components/responses/Forbidden' }
|
|
973
1303
|
'404': { $ref: '#/components/responses/NotFound' }
|
|
974
1304
|
'429': { $ref: '#/components/responses/RateLimited' }
|
|
975
1305
|
'500': { $ref: '#/components/responses/InternalError' }
|
|
976
1306
|
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
in: header
|
|
982
|
-
name: x-api-key
|
|
1307
|
+
/v1/soundlinks/{soundlinkId}/metrics/breakdown:
|
|
1308
|
+
get:
|
|
1309
|
+
operationId: getSoundlinkMetricsBreakdown
|
|
1310
|
+
summary: Soundlink metrics breakdown
|
|
983
1311
|
description: |
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
**Deprecated, retiring 2026-08-17** — migrate to `Authorization: Bearer sk_...` (see `apiKeyBearerAuth`) before then.
|
|
1312
|
+
Per-day metrics broken down by country. One row per
|
|
1313
|
+
`(report_date, soundlink_id, country_code)`. Can be large, so results
|
|
1314
|
+
are paginated.
|
|
988
1315
|
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
Pass your Soundlink `sk_*` API key as a Bearer token:
|
|
994
|
-
`Authorization: Bearer sk_<prefix>_<token>`. Verified with the exact
|
|
995
|
-
same key as `apiKeyAuth` — just the recommended header for the same
|
|
996
|
-
`sk_*` credential. Do not combine with `x-api-key`.
|
|
1316
|
+
**Row schema:** `soundlink_country_daily` v1.0 — the same schema used
|
|
1317
|
+
in JSONL bulk exports. Rows are idempotent on the primary key
|
|
1318
|
+
`(provider, account_id, report_date, soundlink_id, country_code)`;
|
|
1319
|
+
re-ingesting is safe.
|
|
997
1320
|
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
in: path
|
|
1002
|
-
required: true
|
|
1003
|
-
schema:
|
|
1004
|
-
type: string
|
|
1005
|
-
description: Campaign identifier (UUID)
|
|
1321
|
+
**Mutability window:** rows for a given `report_date` can be revised
|
|
1322
|
+
for up to 7 days after the date closes due to delayed Spotify playback
|
|
1323
|
+
events. Re-fetch or re-ingest accordingly.
|
|
1006
1324
|
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
in: header
|
|
1010
|
-
required: true
|
|
1011
|
-
schema:
|
|
1012
|
-
type: string
|
|
1013
|
-
minLength: 1
|
|
1014
|
-
maxLength: 255
|
|
1015
|
-
description: |
|
|
1016
|
-
A unique string identifying this request, used to safely retry write
|
|
1017
|
-
operations (create, stop, budget increase/decrease) without repeating
|
|
1018
|
-
side effects. Required on every request that references this parameter.
|
|
1019
|
-
Reusing this key with an unchanged request body replays the original
|
|
1020
|
-
response; reusing it with a different body returns
|
|
1021
|
-
`409 idempotency_key_conflict`. Keys are honored for 24 hours.
|
|
1325
|
+
Rows contain no financial fields: ads for self-serve soundlinks run
|
|
1326
|
+
in your own Meta account, so spend is not visible to Soundlink.
|
|
1022
1327
|
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
in: query
|
|
1026
|
-
schema:
|
|
1027
|
-
type: integer
|
|
1028
|
-
minimum: 1
|
|
1029
|
-
default: 1
|
|
1030
|
-
description: Page number (1-indexed)
|
|
1328
|
+
Maps to the **Countries** tab in the Soundlink Insights UI.
|
|
1329
|
+
Use `/metrics/timeseries` for country-aggregated daily Trends rows.
|
|
1031
1330
|
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
|
-
|
|
1055
|
-
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
|
-
|
|
1059
|
-
|
|
1331
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1332
|
+
tags: [Soundlinks]
|
|
1333
|
+
security:
|
|
1334
|
+
- apiKeyBearerAuth: []
|
|
1335
|
+
- oauthBearer: []
|
|
1336
|
+
x-required-scope: soundlinks:read
|
|
1337
|
+
parameters:
|
|
1338
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1339
|
+
- $ref: '#/components/parameters/soundlinkStartDate'
|
|
1340
|
+
- $ref: '#/components/parameters/soundlinkEndDate'
|
|
1341
|
+
- $ref: '#/components/parameters/page'
|
|
1342
|
+
- $ref: '#/components/parameters/pageSize500'
|
|
1343
|
+
- name: sortBy
|
|
1344
|
+
in: query
|
|
1345
|
+
schema:
|
|
1346
|
+
type: string
|
|
1347
|
+
enum: [report_date, country_code]
|
|
1348
|
+
default: report_date
|
|
1349
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
1350
|
+
responses:
|
|
1351
|
+
'200':
|
|
1352
|
+
description: Paginated per-day country rows (`soundlink_country_daily` schema)
|
|
1353
|
+
content:
|
|
1354
|
+
application/json:
|
|
1355
|
+
schema:
|
|
1356
|
+
$ref: '#/components/schemas/SoundlinkBreakdownResponse'
|
|
1357
|
+
example:
|
|
1358
|
+
data:
|
|
1359
|
+
schemaVersion: '1.0'
|
|
1360
|
+
items:
|
|
1361
|
+
- provider: soundlink
|
|
1362
|
+
account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1363
|
+
schema_version: '1.0'
|
|
1364
|
+
report_date: '2026-08-01'
|
|
1365
|
+
report_date_timezone: UTC
|
|
1366
|
+
exported_at: '2026-08-28T03:00:00Z'
|
|
1367
|
+
soundlink_id: V1StGXR8_Z5jdHi6B-myT
|
|
1368
|
+
soundlink_name: Midnight Drive
|
|
1369
|
+
soundlink_target_type: track
|
|
1370
|
+
soundlink_target_isrc: DEXW62500259
|
|
1371
|
+
soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
1372
|
+
soundlink_target_playlist_id: null
|
|
1373
|
+
country_code: US
|
|
1374
|
+
views: 4821
|
|
1375
|
+
link_clicks: 890
|
|
1376
|
+
streams: 203
|
|
1377
|
+
listeners: 145
|
|
1378
|
+
new_listeners: 120
|
|
1379
|
+
returning_listeners: 25
|
|
1380
|
+
new_listener_streams: 160
|
|
1381
|
+
returning_listener_streams: 43
|
|
1382
|
+
followers: 12
|
|
1383
|
+
streams_per_listener: 1.4
|
|
1384
|
+
ctr_lp: 0.185
|
|
1385
|
+
pagination:
|
|
1386
|
+
page: 1
|
|
1387
|
+
pageSize: 50
|
|
1388
|
+
totalCount: 340
|
|
1389
|
+
totalPages: 7
|
|
1390
|
+
meta:
|
|
1391
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1392
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1393
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1394
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1395
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1396
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1397
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1060
1398
|
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1399
|
+
/v1/soundlinks/{soundlinkId}/metrics/breakdown/export:
|
|
1400
|
+
get:
|
|
1401
|
+
operationId: exportSoundlinkMetricsBreakdown
|
|
1402
|
+
summary: Soundlink metrics breakdown export (JSONL)
|
|
1403
|
+
description: |
|
|
1404
|
+
Streams the full country-level metrics dataset for a soundlink as
|
|
1405
|
+
**newline-delimited JSON (JSONL)**. Every line is a complete, valid
|
|
1406
|
+
JSON object conforming to the `soundlink_country_daily` v1.0 schema
|
|
1407
|
+
— identical to the rows returned by `GET /metrics/breakdown` but
|
|
1408
|
+
without pagination or an envelope wrapper.
|
|
1068
1409
|
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
in: query
|
|
1072
|
-
schema:
|
|
1073
|
-
type: string
|
|
1074
|
-
format: date
|
|
1075
|
-
description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
|
|
1410
|
+
Designed for data pipeline consumers: load directly into BigQuery,
|
|
1411
|
+
Snowflake, or any JSONL-aware ingest tool without cursor logic.
|
|
1076
1412
|
|
|
1077
|
-
|
|
1078
|
-
|
|
1413
|
+
**Usage:**
|
|
1414
|
+
```
|
|
1415
|
+
GET /v1/soundlinks/{soundlinkId}/metrics/breakdown/export
|
|
1416
|
+
Accept: application/x-ndjson
|
|
1417
|
+
```
|
|
1079
1418
|
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
requestId:
|
|
1085
|
-
type: string
|
|
1086
|
-
format: uuid
|
|
1087
|
-
description: Server-generated request ID. Include when contacting support.
|
|
1419
|
+
**Date range:** if you omit both dates, defaults to the last **90 days**
|
|
1420
|
+
ending today. Override with `startDate` / `endDate`. **Responses are
|
|
1421
|
+
capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
|
|
1422
|
+
Page longer histories in 90-day slices.
|
|
1088
1423
|
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
page:
|
|
1094
|
-
type: integer
|
|
1095
|
-
pageSize:
|
|
1096
|
-
type: integer
|
|
1097
|
-
totalCount:
|
|
1098
|
-
type: integer
|
|
1099
|
-
totalPages:
|
|
1100
|
-
type: integer
|
|
1424
|
+
**Mutability:** rows for a given `report_date` can be revised for up
|
|
1425
|
+
to 7 days after the date closes due to delayed Spotify playback
|
|
1426
|
+
events. Re-fetching and re-ingesting on the primary key is safe
|
|
1427
|
+
(idempotent).
|
|
1101
1428
|
|
|
1102
|
-
|
|
1103
|
-
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
- insufficient_scope
|
|
1115
|
-
- not_found
|
|
1116
|
-
- campaign_not_found
|
|
1117
|
-
- invalid_query_parameter
|
|
1118
|
-
- invalid_date_range
|
|
1119
|
-
- page_size_exceeded
|
|
1120
|
-
- invalid_request
|
|
1121
|
-
- invalid_genre
|
|
1122
|
-
- invalid_duration_or_budget
|
|
1123
|
-
- invalid_daily_budget
|
|
1124
|
-
- invalid_duration_days
|
|
1125
|
-
- invalid_spotify_url
|
|
1126
|
-
- invalid_tier_budget_allocation
|
|
1127
|
-
- invalid_tier_status
|
|
1128
|
-
- tier_update_cooldown
|
|
1129
|
-
- wallet_not_enabled
|
|
1130
|
-
- insufficient_credit
|
|
1131
|
-
- idempotency_key_conflict
|
|
1132
|
-
- rate_limit_exceeded
|
|
1133
|
-
- invalid_video_url
|
|
1134
|
-
- video_import_limit_exceeded
|
|
1135
|
-
- video_import_session_not_found
|
|
1136
|
-
- internal_error
|
|
1137
|
-
message:
|
|
1138
|
-
type: string
|
|
1139
|
-
description: Human-readable error description. Do not parse programmatically.
|
|
1140
|
-
details:
|
|
1141
|
-
type: object
|
|
1142
|
-
nullable: true
|
|
1429
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1430
|
+
tags: [Soundlinks]
|
|
1431
|
+
security:
|
|
1432
|
+
- apiKeyBearerAuth: []
|
|
1433
|
+
- oauthBearer: []
|
|
1434
|
+
x-required-scope: soundlinks:read
|
|
1435
|
+
parameters:
|
|
1436
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1437
|
+
- $ref: '#/components/parameters/startDate'
|
|
1438
|
+
- $ref: '#/components/parameters/endDate'
|
|
1439
|
+
responses:
|
|
1440
|
+
'200':
|
|
1143
1441
|
description: |
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1442
|
+
JSONL stream. Each line is a `soundlink_country_daily` v1.0 row.
|
|
1443
|
+
Lines are sorted by `(report_date asc, country_code)`.
|
|
1444
|
+
headers:
|
|
1445
|
+
Content-Disposition:
|
|
1446
|
+
schema:
|
|
1447
|
+
type: string
|
|
1448
|
+
description: |
|
|
1449
|
+
`attachment; filename="breakdown_{soundlinkId}_{startDate}_{endDate}.jsonl"`
|
|
1450
|
+
example: 'attachment; filename="breakdown_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
|
|
1451
|
+
X-Row-Count:
|
|
1452
|
+
schema:
|
|
1453
|
+
type: integer
|
|
1454
|
+
description: Total number of rows in the response.
|
|
1455
|
+
content:
|
|
1456
|
+
application/x-ndjson:
|
|
1457
|
+
schema:
|
|
1458
|
+
$ref: '#/components/schemas/SoundlinkCountryDailyRow'
|
|
1459
|
+
example: |
|
|
1460
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"US","views":4821,"link_clicks":890,"streams":203,"listeners":145,"new_listeners":120,"returning_listeners":25,"new_listener_streams":160,"returning_listener_streams":43,"followers":12,"streams_per_listener":1.4,"ctr_lp":0.185}
|
|
1461
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"country_code":"DE","views":2103,"link_clicks":31,"streams":87,"listeners":61,"new_listeners":48,"returning_listeners":13,"new_listener_streams":64,"returning_listener_streams":23,"followers":4,"streams_per_listener":1.43,"ctr_lp":0.0147}
|
|
1462
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1463
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1464
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1465
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1466
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1467
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1148
1468
|
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1469
|
+
/v1/soundlinks/{soundlinkId}/metrics/engagement:
|
|
1470
|
+
get:
|
|
1471
|
+
operationId: getSoundlinkEngagement
|
|
1472
|
+
summary: Soundlink engagement breakdown
|
|
1473
|
+
description: |
|
|
1474
|
+
Per-day, per-track engagement metrics for a soundlink. One row per
|
|
1475
|
+
`(report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
1476
|
+
Results are paginated.
|
|
1157
1477
|
|
|
1158
|
-
|
|
1478
|
+
**Row schema:** `soundlink_engagement_daily` v1.0 — the same schema used
|
|
1479
|
+
in JSONL bulk exports. Rows are idempotent on the primary key; re-ingesting
|
|
1480
|
+
is safe.
|
|
1159
1481
|
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1482
|
+
**Key difference from `/metrics/breakdown`:** breakdown aggregates
|
|
1483
|
+
views, streams, and listeners by **country** (`soundlink_country_daily`);
|
|
1484
|
+
engagement breaks down **which tracks** listeners played, including
|
|
1485
|
+
catalog spillover and playlist slot performance (`engagement_context`,
|
|
1486
|
+
`engaged_spotify_track_id`).
|
|
1163
1487
|
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
organizationId,
|
|
1170
|
-
status,
|
|
1171
|
-
socialPlatform,
|
|
1172
|
-
dailyBudget,
|
|
1173
|
-
totalBudget,
|
|
1174
|
-
campaignDuration,
|
|
1175
|
-
generation,
|
|
1176
|
-
createdAt,
|
|
1177
|
-
updatedAt,
|
|
1178
|
-
]
|
|
1179
|
-
properties:
|
|
1180
|
-
campaignId:
|
|
1181
|
-
type: string
|
|
1182
|
-
organizationId:
|
|
1183
|
-
type: string
|
|
1184
|
-
status:
|
|
1185
|
-
$ref: '#/components/schemas/CampaignStatus'
|
|
1186
|
-
socialPlatform:
|
|
1187
|
-
type: string
|
|
1188
|
-
enum: [meta]
|
|
1189
|
-
dailyBudget:
|
|
1190
|
-
type: number
|
|
1191
|
-
description: USD
|
|
1192
|
-
totalBudget:
|
|
1193
|
-
type: number
|
|
1194
|
-
description: USD
|
|
1195
|
-
campaignDuration:
|
|
1196
|
-
type: integer
|
|
1197
|
-
description: Duration in days
|
|
1198
|
-
generation:
|
|
1199
|
-
type: integer
|
|
1200
|
-
enum: [1, 2, 3]
|
|
1201
|
-
description: |
|
|
1202
|
-
Campaign resource generation. `1` = Stripe / one-time / subscription /
|
|
1203
|
-
legacy; `2` = Soundlink managed; `3` = wallet. Public API write
|
|
1204
|
-
operations (budget changes, stop, tier updates) are supported for
|
|
1205
|
-
generation `3` only.
|
|
1206
|
-
createdAt:
|
|
1207
|
-
type: string
|
|
1208
|
-
format: date-time
|
|
1209
|
-
updatedAt:
|
|
1210
|
-
type: string
|
|
1211
|
-
format: date-time
|
|
1488
|
+
**`engagement_context` values:**
|
|
1489
|
+
- `catalog` — same-artist spillover (and direct promoted-track plays)
|
|
1490
|
+
on track soundlinks.
|
|
1491
|
+
- `playlist` — per-track performance inside the promoted playlist on
|
|
1492
|
+
playlist soundlinks.
|
|
1212
1493
|
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
- $ref: '#/components/schemas/CampaignSummary'
|
|
1216
|
-
- type: object
|
|
1217
|
-
properties:
|
|
1218
|
-
strategyType:
|
|
1219
|
-
type: string
|
|
1220
|
-
description: |
|
|
1221
|
-
Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
|
|
1222
|
-
Set at campaign creation.
|
|
1494
|
+
**`listeners` is deduplicated within each row only.** Do not sum
|
|
1495
|
+
`listeners` across days to get a soundlink total.
|
|
1223
1496
|
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
properties:
|
|
1228
|
-
data:
|
|
1229
|
-
type: object
|
|
1230
|
-
required: [items, pagination]
|
|
1231
|
-
properties:
|
|
1232
|
-
items:
|
|
1233
|
-
type: array
|
|
1234
|
-
items:
|
|
1235
|
-
$ref: '#/components/schemas/CampaignSummary'
|
|
1236
|
-
pagination:
|
|
1237
|
-
$ref: '#/components/schemas/Pagination'
|
|
1238
|
-
meta:
|
|
1239
|
-
$ref: '#/components/schemas/Meta'
|
|
1497
|
+
**Date range:** if you omit both dates, defaults to the last **90 days**
|
|
1498
|
+
ending today. Override with `startDate` / `endDate`. **Responses are
|
|
1499
|
+
capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
|
|
1240
1500
|
|
|
1241
|
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
properties:
|
|
1245
|
-
data:
|
|
1246
|
-
$ref: '#/components/schemas/CampaignDetail'
|
|
1247
|
-
meta:
|
|
1248
|
-
$ref: '#/components/schemas/Meta'
|
|
1501
|
+
**Mutability window:** rows for a given `report_date` can be revised
|
|
1502
|
+
for up to 7 days after the date closes due to delayed Spotify
|
|
1503
|
+
playback events.
|
|
1249
1504
|
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
1255
|
-
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1265
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1505
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1506
|
+
tags: [Soundlinks]
|
|
1507
|
+
security:
|
|
1508
|
+
- apiKeyBearerAuth: []
|
|
1509
|
+
- oauthBearer: []
|
|
1510
|
+
x-required-scope: soundlinks:read
|
|
1511
|
+
parameters:
|
|
1512
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1513
|
+
- $ref: '#/components/parameters/startDate'
|
|
1514
|
+
- $ref: '#/components/parameters/endDate'
|
|
1515
|
+
- name: engagementContext
|
|
1516
|
+
in: query
|
|
1517
|
+
schema:
|
|
1518
|
+
type: string
|
|
1519
|
+
enum: [catalog, playlist]
|
|
1520
|
+
description: Filter to a single engagement context. Omit to return both.
|
|
1521
|
+
- $ref: '#/components/parameters/page'
|
|
1522
|
+
- $ref: '#/components/parameters/pageSize500'
|
|
1523
|
+
- name: sortBy
|
|
1524
|
+
in: query
|
|
1525
|
+
schema:
|
|
1526
|
+
type: string
|
|
1527
|
+
enum: [report_date]
|
|
1528
|
+
default: report_date
|
|
1529
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
1530
|
+
responses:
|
|
1531
|
+
'200':
|
|
1532
|
+
description: Paginated engagement rows (`soundlink_engagement_daily` schema)
|
|
1533
|
+
content:
|
|
1534
|
+
application/json:
|
|
1535
|
+
schema:
|
|
1536
|
+
$ref: '#/components/schemas/SoundlinkEngagementResponse'
|
|
1537
|
+
example:
|
|
1538
|
+
data:
|
|
1539
|
+
schemaVersion: '1.0'
|
|
1540
|
+
items:
|
|
1541
|
+
- provider: soundlink
|
|
1542
|
+
account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
1543
|
+
schema_version: '1.0'
|
|
1544
|
+
report_date: '2026-08-01'
|
|
1545
|
+
report_date_timezone: UTC
|
|
1546
|
+
exported_at: '2026-08-28T03:00:00Z'
|
|
1547
|
+
soundlink_id: V1StGXR8_Z5jdHi6B-myT
|
|
1548
|
+
soundlink_name: Midnight Drive
|
|
1549
|
+
soundlink_target_type: track
|
|
1550
|
+
soundlink_target_isrc: DEXW62500259
|
|
1551
|
+
soundlink_target_spotify_track_id: 11dFghVXANMlKmJXsNCbNl
|
|
1552
|
+
soundlink_target_playlist_id: null
|
|
1553
|
+
engagement_context: catalog
|
|
1554
|
+
country_code: US
|
|
1555
|
+
engaged_track_isrc: DEXW62500001
|
|
1556
|
+
engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
|
|
1557
|
+
engaged_track_name: Till The Sunrise
|
|
1558
|
+
playlist_position: null
|
|
1559
|
+
new_listeners: 42
|
|
1560
|
+
returning_listeners: 18
|
|
1561
|
+
listeners: 60
|
|
1562
|
+
new_listener_streams: 58
|
|
1563
|
+
returning_listener_streams: 31
|
|
1564
|
+
streams: 89
|
|
1565
|
+
spl: 1.48
|
|
1566
|
+
pagination:
|
|
1567
|
+
page: 1
|
|
1568
|
+
pageSize: 50
|
|
1569
|
+
totalCount: 120
|
|
1570
|
+
totalPages: 3
|
|
1571
|
+
meta:
|
|
1572
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1573
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1574
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1575
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1576
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1577
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1578
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1268
1579
|
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
if tiers have never been updated.
|
|
1280
|
-
tiers:
|
|
1281
|
-
type: array
|
|
1282
|
-
items:
|
|
1283
|
-
$ref: '#/components/schemas/CampaignTier'
|
|
1580
|
+
/v1/soundlinks/{soundlinkId}/metrics/engagement/export:
|
|
1581
|
+
get:
|
|
1582
|
+
operationId: exportSoundlinkEngagement
|
|
1583
|
+
summary: Soundlink engagement export (JSONL)
|
|
1584
|
+
description: |
|
|
1585
|
+
Streams the full engagement dataset for a soundlink as
|
|
1586
|
+
**newline-delimited JSON (JSONL)**. Every line is a complete, valid
|
|
1587
|
+
JSON object conforming to the `soundlink_engagement_daily` v1.0 schema
|
|
1588
|
+
— identical to the rows returned by `GET /metrics/engagement` but
|
|
1589
|
+
without pagination or an envelope wrapper.
|
|
1284
1590
|
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
required: [data, meta]
|
|
1288
|
-
properties:
|
|
1289
|
-
data:
|
|
1290
|
-
$ref: '#/components/schemas/CampaignTiersData'
|
|
1291
|
-
meta:
|
|
1292
|
-
$ref: '#/components/schemas/Meta'
|
|
1591
|
+
Designed for data pipeline consumers: load directly into BigQuery,
|
|
1592
|
+
Snowflake, or any JSONL-aware ingest tool without cursor logic.
|
|
1293
1593
|
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
|
-
|
|
1298
|
-
|
|
1299
|
-
type: integer
|
|
1300
|
-
minimum: 1
|
|
1301
|
-
description: Targeting tier identifier.
|
|
1302
|
-
isEnabled:
|
|
1303
|
-
type: boolean
|
|
1304
|
-
description: Whether to enable or disable this tier.
|
|
1305
|
-
newAllocationPercent:
|
|
1306
|
-
type: number
|
|
1307
|
-
minimum: 0
|
|
1308
|
-
maximum: 100
|
|
1309
|
-
description: New budget share for this tier (all items must sum to 100).
|
|
1594
|
+
**Usage:**
|
|
1595
|
+
```
|
|
1596
|
+
GET /v1/soundlinks/{soundlinkId}/metrics/engagement/export
|
|
1597
|
+
Accept: application/x-ndjson
|
|
1598
|
+
```
|
|
1310
1599
|
|
|
1311
|
-
|
|
1312
|
-
|
|
1313
|
-
|
|
1314
|
-
|
|
1315
|
-
|
|
1316
|
-
type: array
|
|
1317
|
-
minItems: 1
|
|
1318
|
-
items:
|
|
1319
|
-
$ref: '#/components/schemas/TierStatusUpdateItem'
|
|
1600
|
+
**Response body (one JSON object per line, no trailing comma):**
|
|
1601
|
+
```
|
|
1602
|
+
{"provider":"soundlink","report_date":"2026-08-01","streams":89,...}
|
|
1603
|
+
{"provider":"soundlink","report_date":"2026-08-02","streams":104,...}
|
|
1604
|
+
```
|
|
1320
1605
|
|
|
1321
|
-
|
|
1322
|
-
|
|
1323
|
-
|
|
1324
|
-
|
|
1325
|
-
- Alternative/Indie
|
|
1326
|
-
- Ambient/Sleep
|
|
1327
|
-
- Chill/Background
|
|
1328
|
-
- Classical
|
|
1329
|
-
- Country
|
|
1330
|
-
- Electronic/Dance
|
|
1331
|
-
- Hip-Hop/R&B
|
|
1332
|
-
- Latin/Reggaeton
|
|
1333
|
-
- Pop
|
|
1334
|
-
- Rock
|
|
1335
|
-
- Christmas
|
|
1606
|
+
**Date range:** if you omit both dates, defaults to the last **90 days**
|
|
1607
|
+
ending today. Override with `startDate` / `endDate`. **Responses are
|
|
1608
|
+
capped at 90 days** — a wider range returns `400 invalid_query_parameter`.
|
|
1609
|
+
Page longer histories in 90-day slices.
|
|
1336
1610
|
|
|
1337
|
-
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
- maximum_growth
|
|
1341
|
-
- market_discovery
|
|
1342
|
-
- revenue_maximization
|
|
1343
|
-
- custom
|
|
1611
|
+
**Mutability:** rows for a given `report_date` can be revised for up to
|
|
1612
|
+
7 days after the date closes. Re-fetching and re-ingesting on the
|
|
1613
|
+
primary key is safe (idempotent).
|
|
1344
1614
|
|
|
1345
|
-
|
|
1615
|
+
Requires the `soundlinks:read` scope. Accepts API key or OAuth Bearer.
|
|
1616
|
+
tags: [Soundlinks]
|
|
1617
|
+
security:
|
|
1618
|
+
- apiKeyBearerAuth: []
|
|
1619
|
+
- oauthBearer: []
|
|
1620
|
+
x-required-scope: soundlinks:read
|
|
1621
|
+
parameters:
|
|
1622
|
+
- $ref: '#/components/parameters/soundlinkId'
|
|
1623
|
+
- $ref: '#/components/parameters/startDate'
|
|
1624
|
+
- $ref: '#/components/parameters/endDate'
|
|
1625
|
+
- name: engagementContext
|
|
1626
|
+
in: query
|
|
1627
|
+
schema:
|
|
1628
|
+
type: string
|
|
1629
|
+
enum: [catalog, playlist]
|
|
1630
|
+
description: Filter to a single engagement context. Omit to return both.
|
|
1631
|
+
responses:
|
|
1632
|
+
'200':
|
|
1633
|
+
description: |
|
|
1634
|
+
JSONL stream. Each line is a `soundlink_engagement_daily` v1.0 row.
|
|
1635
|
+
Lines are sorted by `(report_date asc, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
1636
|
+
headers:
|
|
1637
|
+
Content-Disposition:
|
|
1638
|
+
schema:
|
|
1639
|
+
type: string
|
|
1640
|
+
description: |
|
|
1641
|
+
`attachment; filename="engagement_{soundlinkId}_{startDate}_{endDate}.jsonl"`
|
|
1642
|
+
example: 'attachment; filename="engagement_V1StGXR8_Z5jdHi6B-myT_2026-08-01_2026-08-31.jsonl"'
|
|
1643
|
+
X-Row-Count:
|
|
1644
|
+
schema:
|
|
1645
|
+
type: integer
|
|
1646
|
+
description: Total number of rows in the response. Useful for progress tracking when streaming.
|
|
1647
|
+
content:
|
|
1648
|
+
application/x-ndjson:
|
|
1649
|
+
schema:
|
|
1650
|
+
$ref: '#/components/schemas/SoundlinkEngagementDailyRow'
|
|
1651
|
+
example: |
|
|
1652
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"track","soundlink_target_isrc":"DEXW62500259","soundlink_target_spotify_track_id":"11dFghVXANMlKmJXsNCbNl","soundlink_target_playlist_id":null,"engagement_context":"catalog","country_code":"US","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":null,"new_listeners":42,"returning_listeners":18,"listeners":60,"new_listener_streams":58,"returning_listener_streams":31,"streams":89,"spl":1.48}
|
|
1653
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-08-01","report_date_timezone":"UTC","exported_at":"2026-08-28T03:00:00Z","soundlink_id":"V1StGXR8_Z5jdHi6B-myT","soundlink_name":"Midnight Drive","soundlink_target_type":"playlist","soundlink_target_isrc":null,"soundlink_target_spotify_track_id":null,"soundlink_target_playlist_id":"37i9dQZF1Epwit2GR54N9P","engagement_context":"playlist","country_code":"DE","engaged_track_isrc":"DEXW62500001","engaged_spotify_track_id":"4cOdK2wGLETKBW3PvgPWqT","engaged_track_name":"Till The Sunrise","playlist_position":14,"new_listeners":19,"returning_listeners":7,"listeners":26,"new_listener_streams":24,"returning_listener_streams":11,"streams":35,"spl":1.35}
|
|
1654
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1655
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1656
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1657
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1658
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1659
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1660
|
+
|
|
1661
|
+
/v1/videos/import:
|
|
1662
|
+
post:
|
|
1663
|
+
operationId: importVideo
|
|
1664
|
+
summary: Import video(s) from public HTTPS MP4 URL(s)
|
|
1346
1665
|
description: |
|
|
1347
|
-
|
|
1348
|
-
|
|
1349
|
-
oneOf:
|
|
1350
|
-
- $ref: '#/components/schemas/DoItForMeCreativeDirection'
|
|
1351
|
-
- $ref: '#/components/schemas/FullControlCreativeDirection'
|
|
1352
|
-
discriminator:
|
|
1353
|
-
propertyName: type
|
|
1354
|
-
mapping:
|
|
1355
|
-
do_it_for_me: '#/components/schemas/DoItForMeCreativeDirection'
|
|
1356
|
-
full_control: '#/components/schemas/FullControlCreativeDirection'
|
|
1666
|
+
Accepts a single `url` or a `videos` array (1–5 items). Creates one upload
|
|
1667
|
+
session, enqueues async download/staging, and returns `202` with `sessionId`.
|
|
1357
1668
|
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1362
|
-
type:
|
|
1363
|
-
type: string
|
|
1364
|
-
enum: [do_it_for_me]
|
|
1365
|
-
description: Soundlink selects and produces the ad creative.
|
|
1669
|
+
Requires the `videos:write` scope. Subject to a stricter per-credential rate
|
|
1670
|
+
limit than generic public API routes (default 20 imports per hour per API key
|
|
1671
|
+
or OAuth grant). This caps how many import requests are accepted per hour,
|
|
1672
|
+
not how long ingestion takes.
|
|
1366
1673
|
|
|
1367
|
-
|
|
1368
|
-
|
|
1369
|
-
|
|
1370
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1674
|
+
Poll `GET /v1/videos/import/{sessionId}` until `status` is `ready`, `partial`,
|
|
1675
|
+
or `failed`. For single-URL imports, use `videoId` when ready. For batches
|
|
1676
|
+
(`count > 1`), use `videoIds`.
|
|
1677
|
+
tags: [Videos]
|
|
1678
|
+
security:
|
|
1679
|
+
- apiKeyBearerAuth: []
|
|
1680
|
+
- oauthBearer: []
|
|
1681
|
+
x-required-scope: videos:write
|
|
1682
|
+
requestBody:
|
|
1683
|
+
required: true
|
|
1684
|
+
content:
|
|
1685
|
+
application/json:
|
|
1686
|
+
schema:
|
|
1687
|
+
$ref: '#/components/schemas/VideoImportRequest'
|
|
1688
|
+
examples:
|
|
1689
|
+
single:
|
|
1690
|
+
summary: Single URL (legacy)
|
|
1691
|
+
value:
|
|
1692
|
+
url: 'https://cdn.example.com/promo.mp4'
|
|
1693
|
+
batch:
|
|
1694
|
+
summary: Batch of URLs
|
|
1695
|
+
value:
|
|
1696
|
+
videos:
|
|
1697
|
+
- url: 'https://cdn.example.com/a.mp4'
|
|
1698
|
+
- url: 'https://cdn.example.com/b.mp4'
|
|
1699
|
+
responses:
|
|
1700
|
+
'200':
|
|
1701
|
+
description: Duplicate video already in the organization's library (sync legacy path only)
|
|
1702
|
+
content:
|
|
1703
|
+
application/json:
|
|
1704
|
+
schema:
|
|
1705
|
+
$ref: '#/components/schemas/VideoImportStartResponse'
|
|
1706
|
+
'202':
|
|
1707
|
+
description: Import accepted; ingestion in progress
|
|
1708
|
+
content:
|
|
1709
|
+
application/json:
|
|
1710
|
+
schema:
|
|
1711
|
+
$ref: '#/components/schemas/VideoImportStartResponse'
|
|
1712
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
1713
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1714
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1715
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1716
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1380
1717
|
|
|
1381
|
-
|
|
1382
|
-
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1389
|
-
|
|
1390
|
-
|
|
1718
|
+
/v1/videos/import/{sessionId}:
|
|
1719
|
+
get:
|
|
1720
|
+
operationId: getVideoImportStatus
|
|
1721
|
+
summary: Get video import session status
|
|
1722
|
+
description: |
|
|
1723
|
+
Returns processing status. For single-URL sessions, includes `videoId` when ready.
|
|
1724
|
+
For batch sessions (`count > 1`), includes `videoIds` and `counts`.
|
|
1725
|
+
Requires the `videos:write` scope.
|
|
1726
|
+
tags: [Videos]
|
|
1727
|
+
security:
|
|
1728
|
+
- apiKeyBearerAuth: []
|
|
1729
|
+
- oauthBearer: []
|
|
1730
|
+
x-required-scope: videos:write
|
|
1731
|
+
parameters:
|
|
1732
|
+
- name: sessionId
|
|
1733
|
+
in: path
|
|
1734
|
+
required: true
|
|
1735
|
+
schema:
|
|
1736
|
+
type: string
|
|
1737
|
+
format: uuid
|
|
1738
|
+
description: Upload session ID returned by `POST /v1/videos/import`
|
|
1739
|
+
responses:
|
|
1740
|
+
'200':
|
|
1741
|
+
description: Import session status
|
|
1742
|
+
content:
|
|
1743
|
+
application/json:
|
|
1744
|
+
schema:
|
|
1745
|
+
$ref: '#/components/schemas/VideoImportStatusResponse'
|
|
1746
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
1747
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
1748
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
1749
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
1750
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
1391
1751
|
|
|
1392
|
-
|
|
1752
|
+
components:
|
|
1753
|
+
securitySchemes:
|
|
1754
|
+
apiKeyBearerAuth:
|
|
1755
|
+
type: http
|
|
1756
|
+
scheme: bearer
|
|
1757
|
+
description: |
|
|
1758
|
+
Pass your Soundlink `sk_*` API key as a Bearer token:
|
|
1759
|
+
`Authorization: Bearer sk_<prefix>_<token>` (not an OAuth token; see
|
|
1760
|
+
`oauthBearer` for that). Accepted on all Public API operations. Send
|
|
1761
|
+
only one `Authorization` header per request.
|
|
1762
|
+
|
|
1763
|
+
oauthBearer:
|
|
1764
|
+
type: http
|
|
1765
|
+
scheme: bearer
|
|
1766
|
+
bearerFormat: JWT
|
|
1767
|
+
description: |
|
|
1768
|
+
OAuth 2.0 access token from Sign in with Soundlink
|
|
1769
|
+
(`Authorization: Bearer <oauth_access_token>`).
|
|
1770
|
+
Token scopes must include the operation's required scope
|
|
1771
|
+
(see `x-required-scope` and the Authentication section).
|
|
1772
|
+
Accepted on all Public API operations (reads and writes).
|
|
1773
|
+
|
|
1774
|
+
parameters:
|
|
1775
|
+
campaignId:
|
|
1776
|
+
name: campaignId
|
|
1777
|
+
in: path
|
|
1778
|
+
required: true
|
|
1779
|
+
schema:
|
|
1780
|
+
type: string
|
|
1781
|
+
description: Campaign identifier (UUID)
|
|
1782
|
+
|
|
1783
|
+
idempotencyKey:
|
|
1784
|
+
name: Idempotency-Key
|
|
1785
|
+
in: header
|
|
1786
|
+
required: true
|
|
1787
|
+
schema:
|
|
1788
|
+
type: string
|
|
1789
|
+
minLength: 1
|
|
1790
|
+
maxLength: 255
|
|
1791
|
+
description: |
|
|
1792
|
+
A unique string identifying this request, used to safely retry write
|
|
1793
|
+
operations (create, stop, budget increase/decrease) without repeating
|
|
1794
|
+
side effects. Required on every request that references this parameter.
|
|
1795
|
+
Reusing this key with an unchanged request body replays the original
|
|
1796
|
+
response; reusing it with a different body returns
|
|
1797
|
+
`409 idempotency_key_conflict`. Keys are honored for 24 hours.
|
|
1798
|
+
|
|
1799
|
+
page:
|
|
1800
|
+
name: page
|
|
1801
|
+
in: query
|
|
1802
|
+
schema:
|
|
1803
|
+
type: integer
|
|
1804
|
+
minimum: 1
|
|
1805
|
+
default: 1
|
|
1806
|
+
description: Page number (1-indexed)
|
|
1807
|
+
|
|
1808
|
+
pageSize100:
|
|
1809
|
+
name: pageSize
|
|
1810
|
+
in: query
|
|
1811
|
+
schema:
|
|
1812
|
+
type: integer
|
|
1813
|
+
minimum: 1
|
|
1814
|
+
maximum: 100
|
|
1815
|
+
default: 10
|
|
1816
|
+
description: Items per page (max 100)
|
|
1817
|
+
|
|
1818
|
+
pageSize500:
|
|
1819
|
+
name: pageSize
|
|
1820
|
+
in: query
|
|
1821
|
+
schema:
|
|
1822
|
+
type: integer
|
|
1823
|
+
minimum: 1
|
|
1824
|
+
maximum: 500
|
|
1825
|
+
default: 50
|
|
1826
|
+
description: Rows per page (max 500; higher default than list endpoints)
|
|
1827
|
+
|
|
1828
|
+
sortOrder:
|
|
1829
|
+
name: sortOrder
|
|
1830
|
+
in: query
|
|
1831
|
+
schema:
|
|
1832
|
+
type: string
|
|
1833
|
+
enum: [asc, desc]
|
|
1834
|
+
default: desc
|
|
1835
|
+
description: Sort direction
|
|
1836
|
+
|
|
1837
|
+
startDate:
|
|
1838
|
+
name: startDate
|
|
1839
|
+
in: query
|
|
1840
|
+
schema:
|
|
1841
|
+
type: string
|
|
1842
|
+
format: date
|
|
1843
|
+
description: Inclusive start date (`YYYY-MM-DD`). Defaults to campaign start date.
|
|
1844
|
+
|
|
1845
|
+
endDate:
|
|
1846
|
+
name: endDate
|
|
1847
|
+
in: query
|
|
1848
|
+
schema:
|
|
1849
|
+
type: string
|
|
1850
|
+
format: date
|
|
1851
|
+
description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
|
|
1852
|
+
|
|
1853
|
+
soundlinkId:
|
|
1854
|
+
name: soundlinkId
|
|
1855
|
+
in: path
|
|
1856
|
+
required: true
|
|
1857
|
+
schema:
|
|
1858
|
+
type: string
|
|
1859
|
+
description: Soundlink identifier (URL-safe string, same ID used in the public sndl.ink URL)
|
|
1860
|
+
|
|
1861
|
+
soundlinkStartDate:
|
|
1862
|
+
name: startDate
|
|
1863
|
+
in: query
|
|
1864
|
+
schema:
|
|
1865
|
+
type: string
|
|
1866
|
+
format: date
|
|
1867
|
+
description: |
|
|
1868
|
+
Inclusive start date (`YYYY-MM-DD`) for soundlink overview and
|
|
1869
|
+
timeseries. Defaults to the soundlink creation date when omitted.
|
|
1870
|
+
|
|
1871
|
+
soundlinkEndDate:
|
|
1872
|
+
name: endDate
|
|
1873
|
+
in: query
|
|
1874
|
+
schema:
|
|
1875
|
+
type: string
|
|
1876
|
+
format: date
|
|
1877
|
+
description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
|
|
1878
|
+
|
|
1879
|
+
schemas:
|
|
1880
|
+
# --- Shared ---
|
|
1881
|
+
|
|
1882
|
+
Meta:
|
|
1393
1883
|
type: object
|
|
1394
|
-
required: [
|
|
1884
|
+
required: [requestId]
|
|
1395
1885
|
properties:
|
|
1396
|
-
|
|
1397
|
-
type: string
|
|
1398
|
-
countries:
|
|
1399
|
-
type: array
|
|
1400
|
-
items:
|
|
1401
|
-
type: string
|
|
1402
|
-
description: ISO 3166-1 alpha-2 country codes.
|
|
1403
|
-
language:
|
|
1886
|
+
requestId:
|
|
1404
1887
|
type: string
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
type: number
|
|
1408
|
-
description: Share of the campaign budget allocated to this tier. All tiers in a request must sum to 100.
|
|
1888
|
+
format: uuid
|
|
1889
|
+
description: Server-generated request ID. Include when contacting support.
|
|
1409
1890
|
|
|
1410
|
-
|
|
1891
|
+
Pagination:
|
|
1411
1892
|
type: object
|
|
1412
|
-
|
|
1413
|
-
Custom tier targeting. Required when `strategyType` is `custom`: provide a
|
|
1414
|
-
non-empty `customTierIds` and/or `customTiers` array. Omit entirely for
|
|
1415
|
-
non-custom strategies (platform default tiering applies).
|
|
1893
|
+
required: [page, pageSize, totalCount, totalPages]
|
|
1416
1894
|
properties:
|
|
1417
|
-
|
|
1418
|
-
type:
|
|
1419
|
-
|
|
1420
|
-
|
|
1421
|
-
|
|
1422
|
-
type:
|
|
1423
|
-
|
|
1424
|
-
|
|
1425
|
-
tiers (percentBudget > 0) are allowed; inactive (0%) entries do not
|
|
1426
|
-
count toward that limit. Each active tier must receive at least
|
|
1427
|
-
$1.50 of dailyBudget (gross). percentBudget values must sum to 100.
|
|
1428
|
-
items:
|
|
1429
|
-
$ref: '#/components/schemas/CustomTier'
|
|
1895
|
+
page:
|
|
1896
|
+
type: integer
|
|
1897
|
+
pageSize:
|
|
1898
|
+
type: integer
|
|
1899
|
+
totalCount:
|
|
1900
|
+
type: integer
|
|
1901
|
+
totalPages:
|
|
1902
|
+
type: integer
|
|
1430
1903
|
|
|
1431
|
-
|
|
1904
|
+
Error:
|
|
1432
1905
|
type: object
|
|
1433
|
-
required: [
|
|
1906
|
+
required: [code, message]
|
|
1434
1907
|
properties:
|
|
1435
|
-
|
|
1908
|
+
code:
|
|
1436
1909
|
type: string
|
|
1437
|
-
|
|
1438
|
-
|
|
1439
|
-
|
|
1440
|
-
|
|
1441
|
-
|
|
1442
|
-
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
|
-
|
|
1446
|
-
|
|
1447
|
-
|
|
1448
|
-
|
|
1449
|
-
|
|
1450
|
-
|
|
1451
|
-
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
-
|
|
1455
|
-
|
|
1456
|
-
|
|
1457
|
-
|
|
1458
|
-
|
|
1910
|
+
description: Stable snake_case error code.
|
|
1911
|
+
enum:
|
|
1912
|
+
- invalid_api_key
|
|
1913
|
+
- api_key_revoked
|
|
1914
|
+
- api_key_expired
|
|
1915
|
+
- insufficient_scope
|
|
1916
|
+
- not_found
|
|
1917
|
+
- campaign_not_found
|
|
1918
|
+
- invalid_query_parameter
|
|
1919
|
+
- invalid_date_range
|
|
1920
|
+
- page_size_exceeded
|
|
1921
|
+
- invalid_request
|
|
1922
|
+
- invalid_genre
|
|
1923
|
+
- invalid_duration_or_budget
|
|
1924
|
+
- invalid_daily_budget
|
|
1925
|
+
- invalid_duration_days
|
|
1926
|
+
- invalid_spotify_url
|
|
1927
|
+
- invalid_tier_budget_allocation
|
|
1928
|
+
- invalid_tier_status
|
|
1929
|
+
- tier_update_cooldown
|
|
1930
|
+
- wallet_not_enabled
|
|
1931
|
+
- insufficient_credit
|
|
1932
|
+
- idempotency_key_conflict
|
|
1933
|
+
- rate_limit_exceeded
|
|
1934
|
+
- invalid_video_url
|
|
1935
|
+
- video_import_limit_exceeded
|
|
1936
|
+
- video_import_session_not_found
|
|
1937
|
+
- internal_error
|
|
1938
|
+
message:
|
|
1459
1939
|
type: string
|
|
1460
|
-
description:
|
|
1461
|
-
|
|
1462
|
-
$ref: '#/components/schemas/CreativeDirection'
|
|
1463
|
-
trackOptions:
|
|
1940
|
+
description: Human-readable error description. Do not parse programmatically.
|
|
1941
|
+
details:
|
|
1464
1942
|
type: object
|
|
1465
|
-
|
|
1466
|
-
|
|
1467
|
-
|
|
1468
|
-
|
|
1469
|
-
|
|
1470
|
-
|
|
1943
|
+
nullable: true
|
|
1944
|
+
description: |
|
|
1945
|
+
Additive, error-code-specific context (e.g. `available`/`required`
|
|
1946
|
+
on `insufficient_credit`). Absent or `null` for error codes that
|
|
1947
|
+
carry no extra data.
|
|
1948
|
+
additionalProperties: true
|
|
1949
|
+
|
|
1950
|
+
ErrorResponse:
|
|
1951
|
+
type: object
|
|
1952
|
+
required: [error, meta]
|
|
1953
|
+
properties:
|
|
1954
|
+
error:
|
|
1955
|
+
$ref: '#/components/schemas/Error'
|
|
1956
|
+
meta:
|
|
1957
|
+
$ref: '#/components/schemas/Meta'
|
|
1958
|
+
|
|
1959
|
+
# --- Campaign ---
|
|
1960
|
+
|
|
1961
|
+
CampaignStatus:
|
|
1962
|
+
type: string
|
|
1963
|
+
enum: [creating, active, paused, stopped, completed, failed, ended]
|
|
1964
|
+
|
|
1965
|
+
CampaignSummary:
|
|
1966
|
+
type: object
|
|
1967
|
+
required:
|
|
1968
|
+
[
|
|
1969
|
+
campaignId,
|
|
1970
|
+
organizationId,
|
|
1971
|
+
status,
|
|
1972
|
+
socialPlatform,
|
|
1973
|
+
dailyBudget,
|
|
1974
|
+
totalBudget,
|
|
1975
|
+
campaignDuration,
|
|
1976
|
+
generation,
|
|
1977
|
+
createdAt,
|
|
1978
|
+
updatedAt,
|
|
1979
|
+
]
|
|
1980
|
+
properties:
|
|
1981
|
+
campaignId:
|
|
1471
1982
|
type: string
|
|
1472
|
-
|
|
1473
|
-
|
|
1474
|
-
|
|
1475
|
-
|
|
1476
|
-
|
|
1477
|
-
|
|
1983
|
+
organizationId:
|
|
1984
|
+
type: string
|
|
1985
|
+
status:
|
|
1986
|
+
$ref: '#/components/schemas/CampaignStatus'
|
|
1987
|
+
socialPlatform:
|
|
1988
|
+
type: string
|
|
1989
|
+
enum: [meta]
|
|
1990
|
+
dailyBudget:
|
|
1991
|
+
type: number
|
|
1992
|
+
description: USD
|
|
1993
|
+
totalBudget:
|
|
1994
|
+
type: number
|
|
1995
|
+
description: USD
|
|
1996
|
+
campaignDuration:
|
|
1997
|
+
type: integer
|
|
1998
|
+
description: Duration in days
|
|
1999
|
+
generation:
|
|
2000
|
+
type: integer
|
|
2001
|
+
enum: [1, 2, 3]
|
|
2002
|
+
description: |
|
|
2003
|
+
Campaign resource generation. `1` = Stripe / one-time / subscription /
|
|
2004
|
+
legacy; `2` = Soundlink managed; `3` = wallet. Public API write
|
|
2005
|
+
operations (budget changes, stop, tier updates) are supported for
|
|
2006
|
+
generation `3` only.
|
|
2007
|
+
createdAt:
|
|
2008
|
+
type: string
|
|
2009
|
+
format: date-time
|
|
2010
|
+
updatedAt:
|
|
2011
|
+
type: string
|
|
2012
|
+
format: date-time
|
|
1478
2013
|
|
|
1479
|
-
|
|
2014
|
+
CampaignDetail:
|
|
1480
2015
|
allOf:
|
|
1481
|
-
- $ref: '#/components/schemas/
|
|
2016
|
+
- $ref: '#/components/schemas/CampaignSummary'
|
|
1482
2017
|
- type: object
|
|
1483
|
-
required: [strategyType]
|
|
1484
2018
|
properties:
|
|
1485
2019
|
strategyType:
|
|
1486
2020
|
type: string
|
|
1487
|
-
enum:
|
|
1488
|
-
- maximum_growth
|
|
1489
|
-
- market_discovery
|
|
1490
|
-
- revenue_maximization
|
|
1491
2021
|
description: |
|
|
1492
|
-
|
|
1493
|
-
|
|
1494
|
-
not:
|
|
1495
|
-
required: [tierTargeting]
|
|
2022
|
+
Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
|
|
2023
|
+
Set at campaign creation.
|
|
1496
2024
|
|
|
1497
|
-
|
|
1498
|
-
|
|
1499
|
-
|
|
1500
|
-
|
|
1501
|
-
|
|
2025
|
+
CampaignListResponse:
|
|
2026
|
+
type: object
|
|
2027
|
+
required: [data, meta]
|
|
2028
|
+
properties:
|
|
2029
|
+
data:
|
|
2030
|
+
type: object
|
|
2031
|
+
required: [items, pagination]
|
|
1502
2032
|
properties:
|
|
1503
|
-
|
|
1504
|
-
type:
|
|
1505
|
-
|
|
1506
|
-
|
|
1507
|
-
|
|
1508
|
-
|
|
1509
|
-
|
|
1510
|
-
|
|
2033
|
+
items:
|
|
2034
|
+
type: array
|
|
2035
|
+
items:
|
|
2036
|
+
$ref: '#/components/schemas/CampaignSummary'
|
|
2037
|
+
pagination:
|
|
2038
|
+
$ref: '#/components/schemas/Pagination'
|
|
2039
|
+
meta:
|
|
2040
|
+
$ref: '#/components/schemas/Meta'
|
|
1511
2041
|
|
|
1512
|
-
|
|
1513
|
-
|
|
1514
|
-
|
|
1515
|
-
|
|
1516
|
-
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
1520
|
-
|
|
2042
|
+
CampaignDetailResponse:
|
|
2043
|
+
type: object
|
|
2044
|
+
required: [data, meta]
|
|
2045
|
+
properties:
|
|
2046
|
+
data:
|
|
2047
|
+
$ref: '#/components/schemas/CampaignDetail'
|
|
2048
|
+
meta:
|
|
2049
|
+
$ref: '#/components/schemas/Meta'
|
|
2050
|
+
|
|
2051
|
+
CampaignTier:
|
|
2052
|
+
type: object
|
|
2053
|
+
required: [tierId, tierName, isEnabled, allocationPercent]
|
|
2054
|
+
properties:
|
|
2055
|
+
tierId:
|
|
2056
|
+
type: integer
|
|
2057
|
+
description: Targeting tier identifier.
|
|
2058
|
+
tierName:
|
|
2059
|
+
type: string
|
|
2060
|
+
description: Human-readable tier name.
|
|
2061
|
+
isEnabled:
|
|
2062
|
+
type: boolean
|
|
2063
|
+
description: Whether this tier is currently active.
|
|
2064
|
+
allocationPercent:
|
|
2065
|
+
type: number
|
|
2066
|
+
minimum: 0
|
|
2067
|
+
maximum: 100
|
|
2068
|
+
description: Share of campaign budget allocated to this tier.
|
|
2069
|
+
|
|
2070
|
+
CampaignTiersData:
|
|
2071
|
+
type: object
|
|
2072
|
+
required: [lastUpdate, tiers]
|
|
2073
|
+
properties:
|
|
2074
|
+
lastUpdate:
|
|
2075
|
+
type: string
|
|
2076
|
+
format: date-time
|
|
2077
|
+
nullable: true
|
|
2078
|
+
description: |
|
|
2079
|
+
ISO-8601 timestamp of the last manual tier status update, or null
|
|
2080
|
+
if tiers have never been updated.
|
|
2081
|
+
tiers:
|
|
2082
|
+
type: array
|
|
2083
|
+
items:
|
|
2084
|
+
$ref: '#/components/schemas/CampaignTier'
|
|
2085
|
+
|
|
2086
|
+
CampaignTiersResponse:
|
|
2087
|
+
type: object
|
|
2088
|
+
required: [data, meta]
|
|
2089
|
+
properties:
|
|
2090
|
+
data:
|
|
2091
|
+
$ref: '#/components/schemas/CampaignTiersData'
|
|
2092
|
+
meta:
|
|
2093
|
+
$ref: '#/components/schemas/Meta'
|
|
2094
|
+
|
|
2095
|
+
TierStatusUpdateItem:
|
|
2096
|
+
type: object
|
|
2097
|
+
required: [targetingTierId, isEnabled, newAllocationPercent]
|
|
2098
|
+
properties:
|
|
2099
|
+
targetingTierId:
|
|
2100
|
+
type: integer
|
|
2101
|
+
minimum: 1
|
|
2102
|
+
description: Targeting tier identifier.
|
|
2103
|
+
isEnabled:
|
|
2104
|
+
type: boolean
|
|
2105
|
+
description: Whether to enable or disable this tier.
|
|
2106
|
+
newAllocationPercent:
|
|
2107
|
+
type: number
|
|
2108
|
+
minimum: 0
|
|
2109
|
+
maximum: 100
|
|
2110
|
+
description: New budget share for this tier (all items must sum to 100).
|
|
2111
|
+
|
|
2112
|
+
UpdateCampaignTiersRequest:
|
|
2113
|
+
type: object
|
|
2114
|
+
required: [items]
|
|
2115
|
+
properties:
|
|
2116
|
+
items:
|
|
2117
|
+
type: array
|
|
2118
|
+
minItems: 1
|
|
2119
|
+
items:
|
|
2120
|
+
$ref: '#/components/schemas/TierStatusUpdateItem'
|
|
2121
|
+
|
|
2122
|
+
Genre:
|
|
2123
|
+
type: string
|
|
2124
|
+
description: Strictly validated against the platform's genre list.
|
|
2125
|
+
enum:
|
|
2126
|
+
- Alternative/Indie
|
|
2127
|
+
- Ambient/Sleep
|
|
2128
|
+
- Chill/Background
|
|
2129
|
+
- Classical
|
|
2130
|
+
- Country
|
|
2131
|
+
- Electronic/Dance
|
|
2132
|
+
- Hip-Hop/R&B
|
|
2133
|
+
- Latin/Reggaeton
|
|
2134
|
+
- Pop
|
|
2135
|
+
- Rock
|
|
2136
|
+
- Christmas
|
|
2137
|
+
|
|
2138
|
+
StrategyType:
|
|
2139
|
+
type: string
|
|
2140
|
+
enum:
|
|
2141
|
+
- maximum_growth
|
|
2142
|
+
- market_discovery
|
|
2143
|
+
- revenue_maximization
|
|
2144
|
+
- custom
|
|
2145
|
+
|
|
2146
|
+
CreativeDirection:
|
|
2147
|
+
description: |
|
|
2148
|
+
How the campaign's ad creative is produced. Omit entirely to use the
|
|
2149
|
+
platform's default (`do_it_for_me`).
|
|
2150
|
+
oneOf:
|
|
2151
|
+
- $ref: '#/components/schemas/DoItForMeCreativeDirection'
|
|
2152
|
+
- $ref: '#/components/schemas/FullControlCreativeDirection'
|
|
2153
|
+
discriminator:
|
|
2154
|
+
propertyName: type
|
|
2155
|
+
mapping:
|
|
2156
|
+
do_it_for_me: '#/components/schemas/DoItForMeCreativeDirection'
|
|
2157
|
+
full_control: '#/components/schemas/FullControlCreativeDirection'
|
|
2158
|
+
|
|
2159
|
+
DoItForMeCreativeDirection:
|
|
2160
|
+
type: object
|
|
2161
|
+
required: [type]
|
|
2162
|
+
properties:
|
|
2163
|
+
type:
|
|
2164
|
+
type: string
|
|
2165
|
+
enum: [do_it_for_me]
|
|
2166
|
+
description: Soundlink selects and produces the ad creative.
|
|
2167
|
+
|
|
2168
|
+
FullControlCreativeDirection:
|
|
2169
|
+
type: object
|
|
2170
|
+
required: [type, selectedCreatives]
|
|
2171
|
+
properties:
|
|
2172
|
+
type:
|
|
2173
|
+
type: string
|
|
2174
|
+
enum: [full_control]
|
|
2175
|
+
selectedCreatives:
|
|
2176
|
+
type: array
|
|
2177
|
+
minItems: 1
|
|
2178
|
+
items:
|
|
2179
|
+
$ref: '#/components/schemas/SelectedCreative'
|
|
2180
|
+
description: One or more previously imported video creatives to use for the ad. Required for full control.
|
|
2181
|
+
|
|
2182
|
+
SelectedCreative:
|
|
2183
|
+
type: object
|
|
2184
|
+
required: [videoId]
|
|
2185
|
+
properties:
|
|
2186
|
+
videoId:
|
|
2187
|
+
type: string
|
|
2188
|
+
format: uuid
|
|
2189
|
+
description: |
|
|
2190
|
+
ID of a video previously imported into your video library. Import
|
|
2191
|
+
videos via the video import endpoint before referencing them here.
|
|
2192
|
+
|
|
2193
|
+
CustomTier:
|
|
2194
|
+
type: object
|
|
2195
|
+
required: [name, percentBudget]
|
|
2196
|
+
properties:
|
|
2197
|
+
name:
|
|
2198
|
+
type: string
|
|
2199
|
+
countries:
|
|
2200
|
+
type: array
|
|
2201
|
+
items:
|
|
2202
|
+
type: string
|
|
2203
|
+
description: ISO 3166-1 alpha-2 country codes.
|
|
2204
|
+
language:
|
|
2205
|
+
type: string
|
|
2206
|
+
description: ISO 639-1 language code.
|
|
2207
|
+
percentBudget:
|
|
2208
|
+
type: number
|
|
2209
|
+
description: Share of the campaign budget allocated to this tier. All tiers in a request must sum to 100.
|
|
2210
|
+
|
|
2211
|
+
TierTargeting:
|
|
2212
|
+
type: object
|
|
2213
|
+
description: |
|
|
2214
|
+
Custom tier targeting. Required when `strategyType` is `custom`: provide a
|
|
2215
|
+
non-empty `customTierIds` and/or `customTiers` array. Omit entirely for
|
|
2216
|
+
non-custom strategies (platform default tiering applies).
|
|
2217
|
+
properties:
|
|
2218
|
+
customTierIds:
|
|
2219
|
+
type: array
|
|
2220
|
+
items:
|
|
2221
|
+
type: integer
|
|
2222
|
+
customTiers:
|
|
2223
|
+
type: array
|
|
2224
|
+
description: |
|
|
2225
|
+
Inline custom tiers to create with the campaign. At most 5 active
|
|
2226
|
+
tiers (percentBudget > 0) are allowed; inactive (0%) entries do not
|
|
2227
|
+
count toward that limit. Each active tier must receive at least
|
|
2228
|
+
$1.50 of dailyBudget (gross). percentBudget values must sum to 100.
|
|
2229
|
+
items:
|
|
2230
|
+
$ref: '#/components/schemas/CustomTier'
|
|
2231
|
+
|
|
2232
|
+
CreateCampaignRequestShared:
|
|
2233
|
+
type: object
|
|
2234
|
+
required: [spotifyUrl, dailyBudget, durationDays, genre]
|
|
2235
|
+
properties:
|
|
2236
|
+
spotifyUrl:
|
|
2237
|
+
type: string
|
|
2238
|
+
format: uri
|
|
2239
|
+
description: |
|
|
2240
|
+
Spotify track or playlist URL to promote. Must be a valid track or
|
|
2241
|
+
playlist link to a resource that currently exists on Spotify.
|
|
2242
|
+
dailyBudget:
|
|
2243
|
+
type: number
|
|
2244
|
+
minimum: 10
|
|
2245
|
+
description: |
|
|
2246
|
+
USD, per day. Must be at least 10 (same floor as the Soundlink UI).
|
|
2247
|
+
durationDays:
|
|
2248
|
+
description: |
|
|
2249
|
+
Campaign duration in days. Must be an integer from 7 to 30 (UI custom
|
|
2250
|
+
range), or 60, or 90 (UI dropdown extras).
|
|
2251
|
+
oneOf:
|
|
2252
|
+
- type: integer
|
|
2253
|
+
minimum: 7
|
|
2254
|
+
maximum: 30
|
|
2255
|
+
- type: integer
|
|
2256
|
+
enum: [60, 90]
|
|
2257
|
+
genre:
|
|
2258
|
+
$ref: '#/components/schemas/Genre'
|
|
2259
|
+
campaignName:
|
|
2260
|
+
type: string
|
|
2261
|
+
description: Optional. Server generates a default (track title + short random suffix) when omitted.
|
|
2262
|
+
creativeDirection:
|
|
2263
|
+
$ref: '#/components/schemas/CreativeDirection'
|
|
2264
|
+
trackOptions:
|
|
2265
|
+
type: object
|
|
2266
|
+
description: Options that only apply when `spotifyUrl` is a track link. Ignored when `spotifyUrl` is a playlist link.
|
|
2267
|
+
properties:
|
|
2268
|
+
artistIdFollow:
|
|
2269
|
+
type: string
|
|
2270
|
+
description: Pass-through artist identifier.
|
|
2271
|
+
clonedFromCampaignId:
|
|
2272
|
+
type: string
|
|
2273
|
+
format: uuid
|
|
2274
|
+
description: >-
|
|
2275
|
+
Optional UUID of a campaign in your organization this create is
|
|
2276
|
+
cloned from. Records lineage only — it does not copy settings from
|
|
2277
|
+
the source; all other create fields must still be provided. Unknown
|
|
2278
|
+
or other-organization IDs return `400 invalid_request`.
|
|
2279
|
+
|
|
2280
|
+
CreateCampaignRequestWithoutTiers:
|
|
2281
|
+
allOf:
|
|
2282
|
+
- $ref: '#/components/schemas/CreateCampaignRequestShared'
|
|
2283
|
+
- type: object
|
|
2284
|
+
required: [strategyType]
|
|
2285
|
+
properties:
|
|
2286
|
+
strategyType:
|
|
2287
|
+
type: string
|
|
2288
|
+
enum:
|
|
2289
|
+
- maximum_growth
|
|
2290
|
+
- market_discovery
|
|
2291
|
+
- revenue_maximization
|
|
2292
|
+
description: |
|
|
2293
|
+
Non-custom growth strategy. Do not send `tierTargeting` with these
|
|
2294
|
+
values; the platform applies default tiering.
|
|
2295
|
+
not:
|
|
2296
|
+
required: [tierTargeting]
|
|
2297
|
+
|
|
2298
|
+
CreateCampaignRequestCustom:
|
|
2299
|
+
allOf:
|
|
2300
|
+
- $ref: '#/components/schemas/CreateCampaignRequestShared'
|
|
2301
|
+
- type: object
|
|
2302
|
+
required: [strategyType, tierTargeting]
|
|
2303
|
+
properties:
|
|
2304
|
+
strategyType:
|
|
2305
|
+
type: string
|
|
2306
|
+
enum: [custom]
|
|
2307
|
+
description: |
|
|
2308
|
+
Custom growth strategy. Requires `tierTargeting` with a non-empty
|
|
2309
|
+
`customTierIds` and/or `customTiers` array.
|
|
2310
|
+
tierTargeting:
|
|
2311
|
+
$ref: '#/components/schemas/TierTargeting'
|
|
2312
|
+
|
|
2313
|
+
CreateCampaignRequest:
|
|
2314
|
+
description: |
|
|
2315
|
+
Create a wallet-funded campaign. When `strategyType` is `custom`,
|
|
2316
|
+
`tierTargeting` is required. For `maximum_growth`, `market_discovery`,
|
|
2317
|
+
or `revenue_maximization`, do not send `tierTargeting` (platform default
|
|
2318
|
+
tiering applies).
|
|
2319
|
+
oneOf:
|
|
2320
|
+
- $ref: '#/components/schemas/CreateCampaignRequestWithoutTiers'
|
|
2321
|
+
- $ref: '#/components/schemas/CreateCampaignRequestCustom'
|
|
2322
|
+
|
|
2323
|
+
CampaignCreateData:
|
|
2324
|
+
type: object
|
|
2325
|
+
required: [campaignId, status]
|
|
2326
|
+
properties:
|
|
2327
|
+
campaignId:
|
|
2328
|
+
type: string
|
|
2329
|
+
status:
|
|
2330
|
+
$ref: '#/components/schemas/CampaignStatus'
|
|
2331
|
+
|
|
2332
|
+
CreateCampaignResponse:
|
|
2333
|
+
type: object
|
|
2334
|
+
required: [data, meta]
|
|
2335
|
+
properties:
|
|
2336
|
+
data:
|
|
2337
|
+
$ref: '#/components/schemas/CampaignCreateData'
|
|
2338
|
+
meta:
|
|
2339
|
+
$ref: '#/components/schemas/Meta'
|
|
2340
|
+
|
|
2341
|
+
CampaignStopData:
|
|
2342
|
+
type: object
|
|
2343
|
+
required: [campaignId, status]
|
|
2344
|
+
properties:
|
|
2345
|
+
campaignId:
|
|
2346
|
+
type: string
|
|
2347
|
+
status:
|
|
2348
|
+
$ref: '#/components/schemas/CampaignStatus'
|
|
2349
|
+
description: Campaign status after stop (typically `stopped`).
|
|
2350
|
+
|
|
2351
|
+
StopCampaignResponse:
|
|
2352
|
+
type: object
|
|
2353
|
+
required: [data, meta]
|
|
2354
|
+
properties:
|
|
2355
|
+
data:
|
|
2356
|
+
$ref: '#/components/schemas/CampaignStopData'
|
|
2357
|
+
meta:
|
|
2358
|
+
$ref: '#/components/schemas/Meta'
|
|
2359
|
+
|
|
2360
|
+
StrategyCatalogItem:
|
|
2361
|
+
type: object
|
|
2362
|
+
required: [strategyType, tierTargetingAllowed]
|
|
2363
|
+
properties:
|
|
2364
|
+
strategyType:
|
|
2365
|
+
$ref: '#/components/schemas/StrategyType'
|
|
2366
|
+
tierTargetingAllowed:
|
|
2367
|
+
type: boolean
|
|
2368
|
+
description: |
|
|
2369
|
+
When `false`, omit `tierTargeting` on create (platform default
|
|
2370
|
+
tiering applies). Only `custom` allows `tierTargeting`.
|
|
2371
|
+
|
|
2372
|
+
StrategiesCatalogData:
|
|
2373
|
+
type: object
|
|
2374
|
+
required: [strategies]
|
|
2375
|
+
properties:
|
|
2376
|
+
strategies:
|
|
2377
|
+
type: array
|
|
2378
|
+
items:
|
|
2379
|
+
$ref: '#/components/schemas/StrategyCatalogItem'
|
|
2380
|
+
|
|
2381
|
+
StrategiesCatalogResponse:
|
|
2382
|
+
type: object
|
|
2383
|
+
required: [data, meta]
|
|
2384
|
+
properties:
|
|
2385
|
+
data:
|
|
2386
|
+
$ref: '#/components/schemas/StrategiesCatalogData'
|
|
2387
|
+
meta:
|
|
2388
|
+
$ref: '#/components/schemas/Meta'
|
|
2389
|
+
|
|
2390
|
+
BudgetIncreaseMode:
|
|
2391
|
+
type: string
|
|
2392
|
+
enum: [current_cycle, next_renewal, current_and_renewals]
|
|
2393
|
+
description: |
|
|
2394
|
+
Defaults to `current_and_renewals` when omitted on increase requests.
|
|
2395
|
+
|
|
2396
|
+
BudgetDecreaseMode:
|
|
2397
|
+
type: string
|
|
2398
|
+
enum: [current_cycle, current_and_renewals]
|
|
2399
|
+
description: |
|
|
2400
|
+
Defaults to `current_and_renewals` when omitted on decrease requests.
|
|
2401
|
+
`next_renewal` is not supported for decreases.
|
|
2402
|
+
|
|
2403
|
+
IncreaseCampaignBudgetRequest:
|
|
2404
|
+
type: object
|
|
2405
|
+
required: [amount]
|
|
2406
|
+
properties:
|
|
2407
|
+
amount:
|
|
2408
|
+
type: number
|
|
2409
|
+
description: |
|
|
2410
|
+
Wallet debit / top-up amount in USD. Must be positive, except
|
|
2411
|
+
`mode: next_renewal` with `targetDailyBudget` where `amount` may
|
|
2412
|
+
be `0`.
|
|
2413
|
+
mode:
|
|
2414
|
+
$ref: '#/components/schemas/BudgetIncreaseMode'
|
|
2415
|
+
targetDailyBudget:
|
|
2416
|
+
type: number
|
|
2417
|
+
minimum: 0
|
|
2418
|
+
exclusiveMinimum: true
|
|
2419
|
+
description: |
|
|
2420
|
+
Optional absolute next-cycle daily budget (USD). Most useful with
|
|
2421
|
+
`mode: next_renewal`.
|
|
2422
|
+
|
|
2423
|
+
IncreaseCampaignBudgetData:
|
|
2424
|
+
type: object
|
|
2425
|
+
required: [campaignId, mode, amount, walletBalance]
|
|
2426
|
+
properties:
|
|
2427
|
+
campaignId:
|
|
2428
|
+
type: string
|
|
2429
|
+
mode:
|
|
2430
|
+
$ref: '#/components/schemas/BudgetIncreaseMode'
|
|
2431
|
+
amount:
|
|
2432
|
+
type: number
|
|
2433
|
+
walletBalance:
|
|
2434
|
+
type: number
|
|
2435
|
+
description: Organization wallet balance after the increase.
|
|
2436
|
+
walletNextCycleDailyBudget:
|
|
2437
|
+
type: number
|
|
2438
|
+
nullable: true
|
|
2439
|
+
description: Next-cycle daily budget when set by this request.
|
|
2440
|
+
|
|
2441
|
+
IncreaseCampaignBudgetResponse:
|
|
2442
|
+
type: object
|
|
2443
|
+
required: [data, meta]
|
|
2444
|
+
properties:
|
|
2445
|
+
data:
|
|
2446
|
+
$ref: '#/components/schemas/IncreaseCampaignBudgetData'
|
|
2447
|
+
meta:
|
|
2448
|
+
$ref: '#/components/schemas/Meta'
|
|
2449
|
+
|
|
2450
|
+
DecreaseCampaignBudgetRequest:
|
|
2451
|
+
type: object
|
|
2452
|
+
required: [targetDailyBudget]
|
|
2453
|
+
properties:
|
|
2454
|
+
targetDailyBudget:
|
|
2455
|
+
type: number
|
|
2456
|
+
minimum: 10
|
|
2457
|
+
description: |
|
|
2458
|
+
New daily budget in USD (gross). Must be at least `$10`/day and
|
|
2459
|
+
lower than the campaign's current daily budget.
|
|
2460
|
+
mode:
|
|
2461
|
+
$ref: '#/components/schemas/BudgetDecreaseMode'
|
|
2462
|
+
|
|
2463
|
+
DecreaseCampaignBudgetData:
|
|
2464
|
+
type: object
|
|
2465
|
+
required: [campaignId, mode, targetDailyBudget, accepted]
|
|
2466
|
+
properties:
|
|
2467
|
+
campaignId:
|
|
2468
|
+
type: string
|
|
2469
|
+
mode:
|
|
2470
|
+
$ref: '#/components/schemas/BudgetDecreaseMode'
|
|
2471
|
+
targetDailyBudget:
|
|
2472
|
+
type: number
|
|
2473
|
+
accepted:
|
|
2474
|
+
type: boolean
|
|
2475
|
+
enum: [true]
|
|
2476
|
+
description: |
|
|
2477
|
+
Always `true` on success. Unused budget refund is applied
|
|
2478
|
+
asynchronously after acceptance.
|
|
2479
|
+
walletNextCycleDailyBudget:
|
|
2480
|
+
type: number
|
|
2481
|
+
nullable: true
|
|
2482
|
+
description: |
|
|
2483
|
+
Present for `current_and_renewals` when the next-cycle daily
|
|
2484
|
+
budget was updated. Omitted for `current_cycle`.
|
|
2485
|
+
|
|
2486
|
+
DecreaseCampaignBudgetResponse:
|
|
2487
|
+
type: object
|
|
2488
|
+
required: [data, meta]
|
|
2489
|
+
properties:
|
|
2490
|
+
data:
|
|
2491
|
+
$ref: '#/components/schemas/DecreaseCampaignBudgetData'
|
|
2492
|
+
meta:
|
|
2493
|
+
$ref: '#/components/schemas/Meta'
|
|
2494
|
+
|
|
2495
|
+
# --- Metrics ---
|
|
2496
|
+
|
|
2497
|
+
MetricsOverview:
|
|
2498
|
+
type: object
|
|
2499
|
+
description: |
|
|
2500
|
+
Campaign-level totals aggregated across all countries for the requested
|
|
2501
|
+
date range. Field names align with the `campaign_country_daily` row
|
|
2502
|
+
schema — values here are the sum of country rows.
|
|
2503
|
+
required:
|
|
2504
|
+
[
|
|
2505
|
+
listeners,
|
|
2506
|
+
streams,
|
|
2507
|
+
followers,
|
|
2508
|
+
spend_media,
|
|
2509
|
+
spend_total,
|
|
2510
|
+
fees,
|
|
2511
|
+
currency,
|
|
2512
|
+
cpl,
|
|
2513
|
+
cpf,
|
|
2514
|
+
streams_per_listener,
|
|
2515
|
+
]
|
|
2516
|
+
properties:
|
|
2517
|
+
listeners:
|
|
2518
|
+
type: integer
|
|
2519
|
+
description: Unique attributed Spotify listeners (sum of country rows).
|
|
2520
|
+
streams:
|
|
2521
|
+
type: integer
|
|
2522
|
+
description: Attributed Spotify streams (sum of country rows).
|
|
2523
|
+
followers:
|
|
2524
|
+
type: integer
|
|
2525
|
+
description: Attributed artist follower gains (sum of country rows).
|
|
2526
|
+
impressions:
|
|
2527
|
+
type: integer
|
|
2528
|
+
nullable: true
|
|
2529
|
+
description: Total Meta ad impressions. Null if not available.
|
|
2530
|
+
ad_clicks:
|
|
2531
|
+
type: integer
|
|
2532
|
+
nullable: true
|
|
2533
|
+
description: Total Meta ad clicks (all click types).
|
|
2534
|
+
link_clicks:
|
|
2535
|
+
type: integer
|
|
2536
|
+
nullable: true
|
|
2537
|
+
description: Outbound clicks to Spotify via the Soundlink landing page.
|
|
2538
|
+
spend_media:
|
|
2539
|
+
type: number
|
|
2540
|
+
description: Amount billed to Meta for ad delivery. Excludes Soundlink fees. USD.
|
|
2541
|
+
spend_total:
|
|
2542
|
+
type: number
|
|
2543
|
+
description: Total billed by Soundlink (spend_media + fees). USD.
|
|
2544
|
+
fees:
|
|
2545
|
+
type: number
|
|
2546
|
+
description: Soundlink service fee (spend_total - spend_media). USD.
|
|
2547
|
+
currency:
|
|
2548
|
+
type: string
|
|
2549
|
+
description: Currency for spend fields. Currently always `USD`.
|
|
2550
|
+
cpl:
|
|
2551
|
+
type: number
|
|
2552
|
+
description: Cost per listener (spend_media / listeners).
|
|
2553
|
+
cpf:
|
|
2554
|
+
type: number
|
|
2555
|
+
description: Cost per follower (spend_media / followers).
|
|
2556
|
+
streams_per_listener:
|
|
2557
|
+
type: number
|
|
2558
|
+
description: streams / listeners. Zero if listeners is zero.
|
|
2559
|
+
|
|
2560
|
+
MetricsOverviewResponse:
|
|
2561
|
+
type: object
|
|
2562
|
+
required: [data, meta]
|
|
2563
|
+
properties:
|
|
2564
|
+
data:
|
|
2565
|
+
$ref: '#/components/schemas/MetricsOverview'
|
|
2566
|
+
meta:
|
|
2567
|
+
$ref: '#/components/schemas/Meta'
|
|
2568
|
+
|
|
2569
|
+
BreakdownRow:
|
|
2570
|
+
type: object
|
|
2571
|
+
description: |
|
|
2572
|
+
One row of the `campaign_country_daily` v1.0 schema.
|
|
2573
|
+
Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
|
|
2574
|
+
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
2575
|
+
Values for a given `report_date` may be revised for up to 7 days after
|
|
2576
|
+
the date closes due to delayed events from Meta and Spotify.
|
|
2577
|
+
required:
|
|
2578
|
+
- provider
|
|
2579
|
+
- account_id
|
|
2580
|
+
- schema_version
|
|
2581
|
+
- report_date
|
|
2582
|
+
- report_date_timezone
|
|
2583
|
+
- exported_at
|
|
2584
|
+
- campaign_id
|
|
2585
|
+
- campaign_name
|
|
2586
|
+
- campaign_target_type
|
|
2587
|
+
- country_code
|
|
2588
|
+
- streams
|
|
2589
|
+
- listeners
|
|
2590
|
+
- followers
|
|
2591
|
+
- streams_per_listener
|
|
2592
|
+
- spend_media
|
|
2593
|
+
- spend_total
|
|
2594
|
+
- fees
|
|
2595
|
+
- currency
|
|
2596
|
+
- currency_account
|
|
2597
|
+
- cpl
|
|
2598
|
+
- cpf
|
|
2599
|
+
- cost_per_result
|
|
2600
|
+
properties:
|
|
2601
|
+
provider:
|
|
2602
|
+
type: string
|
|
2603
|
+
enum: [soundlink]
|
|
2604
|
+
description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
|
|
2605
|
+
account_id:
|
|
2606
|
+
type: string
|
|
2607
|
+
description: Soundlink organization ID (UUID).
|
|
2608
|
+
schema_version:
|
|
2609
|
+
type: string
|
|
2610
|
+
description: Schema version. Pin your ingest pipeline to this value.
|
|
2611
|
+
example: '1.0'
|
|
2612
|
+
report_date:
|
|
2613
|
+
type: string
|
|
2614
|
+
format: date
|
|
2615
|
+
description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
|
|
2616
|
+
report_date_timezone:
|
|
2617
|
+
type: string
|
|
2618
|
+
enum: [UTC]
|
|
2619
|
+
description: Always `UTC`.
|
|
2620
|
+
exported_at:
|
|
2621
|
+
type: string
|
|
2622
|
+
format: date-time
|
|
2623
|
+
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
2624
|
+
campaign_id:
|
|
2625
|
+
type: string
|
|
2626
|
+
description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
|
|
2627
|
+
campaign_name:
|
|
2628
|
+
type: string
|
|
2629
|
+
description: Human-readable campaign name.
|
|
2630
|
+
campaign_target_type:
|
|
2631
|
+
type: string
|
|
2632
|
+
nullable: true
|
|
2633
|
+
enum: [track, playlist]
|
|
2634
|
+
description: Whether this campaign promotes a track or playlist. `null` if undetermined.
|
|
2635
|
+
campaign_target_isrc:
|
|
2636
|
+
type: string
|
|
2637
|
+
nullable: true
|
|
2638
|
+
description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
|
|
2639
|
+
campaign_target_spotify_track_id:
|
|
2640
|
+
type: string
|
|
2641
|
+
nullable: true
|
|
2642
|
+
description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
|
|
2643
|
+
campaign_target_playlist_id:
|
|
2644
|
+
type: string
|
|
2645
|
+
nullable: true
|
|
2646
|
+
description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
|
|
2647
|
+
country_code:
|
|
2648
|
+
type: string
|
|
2649
|
+
description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
|
|
2650
|
+
impressions:
|
|
2651
|
+
type: integer
|
|
2652
|
+
nullable: true
|
|
2653
|
+
description: Total Meta ad impressions served in this country on this day.
|
|
2654
|
+
ad_clicks:
|
|
2655
|
+
type: integer
|
|
2656
|
+
nullable: true
|
|
2657
|
+
description: Total clicks on the Meta ad (all click types). Use `ctr_adclick` for ad-level CTR.
|
|
2658
|
+
link_clicks:
|
|
2659
|
+
type: integer
|
|
2660
|
+
nullable: true
|
|
2661
|
+
description: Clicks on "Continue with Spotify" on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR.
|
|
2662
|
+
streams:
|
|
2663
|
+
type: integer
|
|
2664
|
+
description: Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.
|
|
2665
|
+
listeners:
|
|
2666
|
+
type: integer
|
|
2667
|
+
description: Unique Spotify listeners attributed to this campaign in this country on this day (7-day click-through window). Summing country rows gives the correct campaign-level total.
|
|
2668
|
+
followers:
|
|
2669
|
+
type: integer
|
|
2670
|
+
description: Spotify artist follower gains attributed to this campaign in this country on this day (7-day click-through window).
|
|
2671
|
+
streams_per_listener:
|
|
2672
|
+
type: number
|
|
2673
|
+
description: streams / listeners for this row. Zero if listeners is zero.
|
|
2674
|
+
spend_media:
|
|
2675
|
+
type: number
|
|
2676
|
+
description: Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In `currency`.
|
|
2677
|
+
spend_total:
|
|
2678
|
+
type: number
|
|
2679
|
+
description: Total billed by Soundlink (spend_media + fees). Computed as `spend_media / (1 - fee_pct)`.
|
|
2680
|
+
fees:
|
|
2681
|
+
type: number
|
|
2682
|
+
description: Soundlink service fee (spend_total - spend_media).
|
|
2683
|
+
currency:
|
|
2684
|
+
type: string
|
|
2685
|
+
description: Currency for spend fields. Currently always `USD`.
|
|
2686
|
+
currency_account:
|
|
2687
|
+
type: string
|
|
2688
|
+
description: Account billing currency. Currently always `USD`. Will differ from `currency` once EUR delivery is available.
|
|
2689
|
+
cpl:
|
|
2690
|
+
type: number
|
|
2691
|
+
description: Cost per listener (spend_media / listeners). Zero if listeners is zero.
|
|
2692
|
+
cpf:
|
|
2693
|
+
type: number
|
|
2694
|
+
description: Cost per follower (spend_media / followers). Zero if followers is zero.
|
|
2695
|
+
cpc_linkclick:
|
|
2696
|
+
type: number
|
|
2697
|
+
nullable: true
|
|
2698
|
+
description: Cost per outbound click (spend_media / link_clicks). Null if link_clicks is null or zero.
|
|
2699
|
+
ctr_linkclick:
|
|
2700
|
+
type: number
|
|
2701
|
+
nullable: true
|
|
2702
|
+
description: Outbound CTR (link_clicks / impressions). Null if impressions is null or zero.
|
|
2703
|
+
ctr_adclick:
|
|
2704
|
+
type: number
|
|
2705
|
+
nullable: true
|
|
2706
|
+
description: Meta ad CTR (ad_clicks / impressions). Null if impressions is null or zero.
|
|
2707
|
+
cost_per_result:
|
|
2708
|
+
type: number
|
|
2709
|
+
description: Cost per primary campaign result. Currently equivalent to `cpf` (cost per follower). See `result_type`.
|
|
2710
|
+
result_type:
|
|
2711
|
+
type: string
|
|
2712
|
+
nullable: true
|
|
2713
|
+
enum: [lp_click, stream, follow]
|
|
2714
|
+
description: The conversion event used for `cost_per_result`. Currently always `follow`.
|
|
2715
|
+
|
|
2716
|
+
MetricsBreakdownResponse:
|
|
2717
|
+
type: object
|
|
2718
|
+
required: [data, meta]
|
|
2719
|
+
properties:
|
|
2720
|
+
data:
|
|
2721
|
+
type: object
|
|
2722
|
+
required: [schemaVersion, items, pagination]
|
|
2723
|
+
properties:
|
|
2724
|
+
schemaVersion:
|
|
2725
|
+
type: string
|
|
2726
|
+
description: Version of the `campaign_country_daily` row schema. Pin your ingest pipeline to this.
|
|
2727
|
+
example: '1.0'
|
|
2728
|
+
items:
|
|
2729
|
+
type: array
|
|
2730
|
+
items:
|
|
2731
|
+
$ref: '#/components/schemas/BreakdownRow'
|
|
2732
|
+
pagination:
|
|
2733
|
+
$ref: '#/components/schemas/Pagination'
|
|
2734
|
+
meta:
|
|
2735
|
+
$ref: '#/components/schemas/Meta'
|
|
2736
|
+
|
|
2737
|
+
MetricsEngagementResponse:
|
|
2738
|
+
type: object
|
|
2739
|
+
required: [data, meta]
|
|
2740
|
+
properties:
|
|
2741
|
+
data:
|
|
2742
|
+
type: object
|
|
2743
|
+
required: [schemaVersion, items, pagination]
|
|
2744
|
+
properties:
|
|
2745
|
+
schemaVersion:
|
|
2746
|
+
type: string
|
|
2747
|
+
description: Version of the `campaign_engagement_daily` row schema. Pin your ingest pipeline to this.
|
|
2748
|
+
example: '1.0'
|
|
2749
|
+
items:
|
|
2750
|
+
type: array
|
|
2751
|
+
items:
|
|
2752
|
+
$ref: '#/components/schemas/EngagementRow'
|
|
2753
|
+
pagination:
|
|
2754
|
+
$ref: '#/components/schemas/Pagination'
|
|
2755
|
+
meta:
|
|
2756
|
+
$ref: '#/components/schemas/Meta'
|
|
2757
|
+
|
|
2758
|
+
# --- Engagement ---
|
|
2759
|
+
|
|
2760
|
+
EngagementRow:
|
|
2761
|
+
type: object
|
|
2762
|
+
description: |
|
|
2763
|
+
One row of the `campaign_engagement_daily` v1.0 schema.
|
|
2764
|
+
Primary key: `(provider, account_id, report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
2765
|
+
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
2766
|
+
Values for a given `report_date` may be revised for up to 7 days after
|
|
2767
|
+
the date closes due to delayed Spotify playback events.
|
|
2768
|
+
required:
|
|
2769
|
+
- provider
|
|
2770
|
+
- account_id
|
|
2771
|
+
- schema_version
|
|
2772
|
+
- report_date
|
|
2773
|
+
- report_date_timezone
|
|
2774
|
+
- exported_at
|
|
2775
|
+
- campaign_id
|
|
2776
|
+
- campaign_name
|
|
2777
|
+
- campaign_target_type
|
|
2778
|
+
- status
|
|
2779
|
+
- engagement_context
|
|
2780
|
+
- country_code
|
|
2781
|
+
- engaged_spotify_track_id
|
|
2782
|
+
- engaged_track_name
|
|
2783
|
+
- new_listeners
|
|
2784
|
+
- returning_listeners
|
|
2785
|
+
- listeners
|
|
2786
|
+
- new_listener_streams
|
|
2787
|
+
- returning_listener_streams
|
|
2788
|
+
- streams
|
|
2789
|
+
- spl
|
|
2790
|
+
properties:
|
|
2791
|
+
provider:
|
|
2792
|
+
type: string
|
|
2793
|
+
enum: [soundlink]
|
|
2794
|
+
description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
|
|
2795
|
+
account_id:
|
|
2796
|
+
type: string
|
|
2797
|
+
description: Soundlink organization ID (UUID).
|
|
2798
|
+
schema_version:
|
|
2799
|
+
type: string
|
|
2800
|
+
description: Schema version string. Pin your ingest pipeline to this value.
|
|
2801
|
+
example: '1.0'
|
|
2802
|
+
report_date:
|
|
2803
|
+
type: string
|
|
2804
|
+
format: date
|
|
2805
|
+
description: UTC calendar date the metrics belong to (`YYYY-MM-DD`). Rows can change for up to 7 days after close.
|
|
2806
|
+
report_date_timezone:
|
|
2807
|
+
type: string
|
|
2808
|
+
enum: [UTC]
|
|
2809
|
+
description: Always `UTC`.
|
|
2810
|
+
exported_at:
|
|
2811
|
+
type: string
|
|
2812
|
+
format: date-time
|
|
2813
|
+
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
2814
|
+
campaign_id:
|
|
2815
|
+
type: string
|
|
2816
|
+
description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
|
|
2817
|
+
campaign_name:
|
|
2818
|
+
type: string
|
|
2819
|
+
description: Human-readable campaign name.
|
|
2820
|
+
campaign_target_type:
|
|
2821
|
+
type: string
|
|
2822
|
+
nullable: true
|
|
2823
|
+
enum: [track, playlist]
|
|
2824
|
+
description: Whether this campaign promotes a track or a playlist. `null` if undetermined.
|
|
2825
|
+
campaign_target_isrc:
|
|
2826
|
+
type: string
|
|
2827
|
+
nullable: true
|
|
2828
|
+
description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
|
|
2829
|
+
campaign_target_spotify_track_id:
|
|
2830
|
+
type: string
|
|
2831
|
+
nullable: true
|
|
2832
|
+
description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
|
|
2833
|
+
campaign_target_playlist_id:
|
|
2834
|
+
type: string
|
|
2835
|
+
nullable: true
|
|
2836
|
+
description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
|
|
2837
|
+
status:
|
|
2838
|
+
type: string
|
|
2839
|
+
enum: [active, ended, scheduled]
|
|
2840
|
+
description: |
|
|
2841
|
+
Campaign lifecycle status on `report_date`.
|
|
2842
|
+
`active` = campaign was running; `ended` = campaign had ended or was refunded;
|
|
2843
|
+
`scheduled` = `report_date` is before campaign start.
|
|
2844
|
+
Post-campaign rows will have `status = ended`.
|
|
2845
|
+
engagement_context:
|
|
2846
|
+
type: string
|
|
2847
|
+
enum: [catalog, playlist]
|
|
2848
|
+
description: |
|
|
2849
|
+
Which dashboard section the row maps to.
|
|
2850
|
+
`catalog` = same-artist spillover (and direct promoted-track plays) on track campaigns.
|
|
2851
|
+
`playlist` = per-track performance inside the promoted playlist on playlist campaigns.
|
|
2852
|
+
country_code:
|
|
2853
|
+
type: string
|
|
2854
|
+
description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
|
|
2855
|
+
example: US
|
|
2856
|
+
engaged_track_isrc:
|
|
2857
|
+
type: string
|
|
2858
|
+
nullable: true
|
|
2859
|
+
description: |
|
|
2860
|
+
ISRC of the track that received listens. May differ from `campaign_target_isrc`
|
|
2861
|
+
for catalog spillover rows. `null` if ISRC could not be resolved.
|
|
2862
|
+
engaged_spotify_track_id:
|
|
2863
|
+
type: string
|
|
2864
|
+
description: |
|
|
2865
|
+
Stable track identifier used in the primary key. Currently this is the
|
|
2866
|
+
Spotify track ID for the engaged track.
|
|
2867
|
+
example: 4cOdK2wGLETKBW3PvgPWqT
|
|
2868
|
+
engaged_track_name:
|
|
2869
|
+
type: string
|
|
2870
|
+
description: Display name of the engaged track.
|
|
2871
|
+
playlist_position:
|
|
2872
|
+
type: integer
|
|
2873
|
+
nullable: true
|
|
2874
|
+
minimum: 1
|
|
2875
|
+
description: |
|
|
2876
|
+
1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
|
|
2877
|
+
Populated only when `engagement_context = playlist` and that day's playlist crawl listed the track.
|
|
2878
|
+
`null` for catalog rows; before the day's crawl completes (current UTC day is often null until later morning UTC);
|
|
2879
|
+
when the track was not listed or could not be matched to that day's crawl; or while historical backfill is still catching up.
|
|
2880
|
+
Field is beta until historical backfill finishes. Treat `null` as unavailable — not an error.
|
|
2881
|
+
new_listeners:
|
|
2882
|
+
type: integer
|
|
2883
|
+
minimum: 0
|
|
2884
|
+
description: Unique listeners whose first play of this track on this smart link occurred on `report_date`.
|
|
2885
|
+
returning_listeners:
|
|
2886
|
+
type: integer
|
|
2887
|
+
minimum: 0
|
|
2888
|
+
description: Unique listeners who played this track on `report_date` but whose first play was on an earlier date.
|
|
2889
|
+
listeners:
|
|
2890
|
+
type: integer
|
|
2891
|
+
minimum: 0
|
|
2892
|
+
description: |
|
|
2893
|
+
Total unique listeners on `report_date`: `new_listeners + returning_listeners`.
|
|
2894
|
+
**Do not sum across days** — the same listener can appear on multiple `report_date` rows.
|
|
2895
|
+
new_listener_streams:
|
|
2896
|
+
type: integer
|
|
2897
|
+
minimum: 0
|
|
2898
|
+
description: Stream count from new listeners on `report_date`.
|
|
2899
|
+
returning_listener_streams:
|
|
2900
|
+
type: integer
|
|
2901
|
+
minimum: 0
|
|
2902
|
+
description: Stream count from returning listeners on `report_date`.
|
|
2903
|
+
streams:
|
|
2904
|
+
type: integer
|
|
2905
|
+
minimum: 0
|
|
2906
|
+
description: |
|
|
2907
|
+
Total streams on `report_date`: `new_listener_streams + returning_listener_streams`.
|
|
2908
|
+
Safe to sum within a day; summing across days counts repeat listens.
|
|
2909
|
+
spl:
|
|
2910
|
+
type: number
|
|
2911
|
+
description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
|
|
1521
2912
|
|
|
1522
|
-
|
|
1523
|
-
type: object
|
|
1524
|
-
required: [campaignId, status]
|
|
1525
|
-
properties:
|
|
1526
|
-
campaignId:
|
|
1527
|
-
type: string
|
|
1528
|
-
status:
|
|
1529
|
-
$ref: '#/components/schemas/CampaignStatus'
|
|
2913
|
+
# --- Soundlinks ---
|
|
1530
2914
|
|
|
1531
|
-
|
|
1532
|
-
type:
|
|
1533
|
-
|
|
1534
|
-
properties:
|
|
1535
|
-
data:
|
|
1536
|
-
$ref: '#/components/schemas/CampaignCreateData'
|
|
1537
|
-
meta:
|
|
1538
|
-
$ref: '#/components/schemas/Meta'
|
|
2915
|
+
SoundlinkStatus:
|
|
2916
|
+
type: string
|
|
2917
|
+
enum: [draft, active, archived]
|
|
1539
2918
|
|
|
1540
|
-
|
|
2919
|
+
SoundlinkSummary:
|
|
1541
2920
|
type: object
|
|
1542
|
-
required: [
|
|
2921
|
+
required: [soundlinkId, organizationId, name, url, targetType, status, createdAt]
|
|
1543
2922
|
properties:
|
|
1544
|
-
|
|
2923
|
+
soundlinkId:
|
|
2924
|
+
type: string
|
|
2925
|
+
description: |
|
|
2926
|
+
Unique ID of this soundlink (URL-safe string, same ID used in the
|
|
2927
|
+
public sndl.ink URL).
|
|
2928
|
+
example: V1StGXR8_Z5jdHi6B-myT
|
|
2929
|
+
organizationId:
|
|
2930
|
+
type: string
|
|
2931
|
+
description: Soundlink organization ID (UUID).
|
|
2932
|
+
name:
|
|
2933
|
+
type: string
|
|
2934
|
+
description: Human-readable soundlink name.
|
|
2935
|
+
url:
|
|
2936
|
+
type: string
|
|
2937
|
+
format: uri
|
|
2938
|
+
description: Public soundlink landing page URL.
|
|
2939
|
+
example: https://sndl.ink/soundlink/V1StGXR8_Z5jdHi6B-myT
|
|
2940
|
+
targetType:
|
|
2941
|
+
type: string
|
|
2942
|
+
nullable: true
|
|
2943
|
+
enum: [track, album, playlist]
|
|
2944
|
+
description: |
|
|
2945
|
+
Type of Spotify resource this soundlink promotes. `null` if the
|
|
2946
|
+
target could not be determined.
|
|
2947
|
+
spotifyUrl:
|
|
1545
2948
|
type: string
|
|
2949
|
+
format: uri
|
|
2950
|
+
nullable: true
|
|
2951
|
+
description: Spotify URL of the promoted resource.
|
|
1546
2952
|
status:
|
|
1547
|
-
$ref: '#/components/schemas/
|
|
1548
|
-
|
|
2953
|
+
$ref: '#/components/schemas/SoundlinkStatus'
|
|
2954
|
+
createdAt:
|
|
2955
|
+
type: string
|
|
2956
|
+
format: date-time
|
|
1549
2957
|
|
|
1550
|
-
|
|
2958
|
+
SoundlinkListResponse:
|
|
1551
2959
|
type: object
|
|
1552
2960
|
required: [data, meta]
|
|
1553
2961
|
properties:
|
|
1554
2962
|
data:
|
|
1555
|
-
|
|
2963
|
+
type: object
|
|
2964
|
+
required: [items, pagination]
|
|
2965
|
+
properties:
|
|
2966
|
+
items:
|
|
2967
|
+
type: array
|
|
2968
|
+
items:
|
|
2969
|
+
$ref: '#/components/schemas/SoundlinkSummary'
|
|
2970
|
+
pagination:
|
|
2971
|
+
$ref: '#/components/schemas/Pagination'
|
|
1556
2972
|
meta:
|
|
1557
2973
|
$ref: '#/components/schemas/Meta'
|
|
1558
2974
|
|
|
1559
|
-
|
|
1560
|
-
|
|
1561
|
-
|
|
1562
|
-
|
|
1563
|
-
|
|
1564
|
-
|
|
1565
|
-
|
|
1566
|
-
|
|
1567
|
-
|
|
1568
|
-
|
|
1569
|
-
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
|
|
1573
|
-
|
|
1574
|
-
|
|
1575
|
-
|
|
1576
|
-
|
|
1577
|
-
|
|
1578
|
-
$ref: '#/components/schemas/StrategyCatalogItem'
|
|
2975
|
+
SoundlinkDetail:
|
|
2976
|
+
allOf:
|
|
2977
|
+
- $ref: '#/components/schemas/SoundlinkSummary'
|
|
2978
|
+
- type: object
|
|
2979
|
+
required: [autoFollow, metaPixelId, tiktokPixelId]
|
|
2980
|
+
properties:
|
|
2981
|
+
autoFollow:
|
|
2982
|
+
type: boolean
|
|
2983
|
+
description: |
|
|
2984
|
+
Whether auto-follow is configured for this soundlink. Whether
|
|
2985
|
+
it takes effect also depends on the organization's plan.
|
|
2986
|
+
metaPixelId:
|
|
2987
|
+
type: string
|
|
2988
|
+
nullable: true
|
|
2989
|
+
description: Meta pixel ID configured on this soundlink. `null` if not set.
|
|
2990
|
+
tiktokPixelId:
|
|
2991
|
+
type: string
|
|
2992
|
+
nullable: true
|
|
2993
|
+
description: TikTok pixel ID configured on this soundlink. `null` if not set.
|
|
1579
2994
|
|
|
1580
|
-
|
|
2995
|
+
SoundlinkDetailResponse:
|
|
1581
2996
|
type: object
|
|
1582
2997
|
required: [data, meta]
|
|
1583
2998
|
properties:
|
|
1584
2999
|
data:
|
|
1585
|
-
$ref: '#/components/schemas/
|
|
3000
|
+
$ref: '#/components/schemas/SoundlinkDetail'
|
|
1586
3001
|
meta:
|
|
1587
3002
|
$ref: '#/components/schemas/Meta'
|
|
1588
3003
|
|
|
1589
|
-
|
|
1590
|
-
type: string
|
|
1591
|
-
enum: [current_cycle, next_renewal, current_and_renewals]
|
|
1592
|
-
description: |
|
|
1593
|
-
Defaults to `current_and_renewals` when omitted on increase requests.
|
|
1594
|
-
|
|
1595
|
-
BudgetDecreaseMode:
|
|
1596
|
-
type: string
|
|
1597
|
-
enum: [current_cycle, current_and_renewals]
|
|
1598
|
-
description: |
|
|
1599
|
-
Defaults to `current_and_renewals` when omitted on decrease requests.
|
|
1600
|
-
`next_renewal` is not supported for decreases.
|
|
1601
|
-
|
|
1602
|
-
IncreaseCampaignBudgetRequest:
|
|
1603
|
-
type: object
|
|
1604
|
-
required: [amount]
|
|
1605
|
-
properties:
|
|
1606
|
-
amount:
|
|
1607
|
-
type: number
|
|
1608
|
-
description: |
|
|
1609
|
-
Wallet debit / top-up amount in USD. Must be positive, except
|
|
1610
|
-
`mode: next_renewal` with `targetDailyBudget` where `amount` may
|
|
1611
|
-
be `0`.
|
|
1612
|
-
mode:
|
|
1613
|
-
$ref: '#/components/schemas/BudgetIncreaseMode'
|
|
1614
|
-
targetDailyBudget:
|
|
1615
|
-
type: number
|
|
1616
|
-
minimum: 0
|
|
1617
|
-
exclusiveMinimum: true
|
|
1618
|
-
description: |
|
|
1619
|
-
Optional absolute next-cycle daily budget (USD). Most useful with
|
|
1620
|
-
`mode: next_renewal`.
|
|
1621
|
-
|
|
1622
|
-
IncreaseCampaignBudgetData:
|
|
3004
|
+
SoundlinkMetricsOverview:
|
|
1623
3005
|
type: object
|
|
1624
|
-
|
|
3006
|
+
description: |
|
|
3007
|
+
Soundlink-level totals for the requested date range. Additive fields
|
|
3008
|
+
are sums of `api_smart_link_country_daily` country-day rows.
|
|
3009
|
+
required: [views, streams, listeners, followers, streams_per_listener]
|
|
1625
3010
|
properties:
|
|
1626
|
-
|
|
1627
|
-
type:
|
|
1628
|
-
|
|
1629
|
-
|
|
1630
|
-
|
|
1631
|
-
type: number
|
|
1632
|
-
walletBalance:
|
|
1633
|
-
type: number
|
|
1634
|
-
description: Organization wallet balance after the increase.
|
|
1635
|
-
walletNextCycleDailyBudget:
|
|
1636
|
-
type: number
|
|
3011
|
+
views:
|
|
3012
|
+
type: integer
|
|
3013
|
+
description: Soundlink landing page views in the period (sum of country-day rows).
|
|
3014
|
+
link_clicks:
|
|
3015
|
+
type: integer
|
|
1637
3016
|
nullable: true
|
|
1638
|
-
description: Next-cycle daily budget when set by this request.
|
|
1639
|
-
|
|
1640
|
-
IncreaseCampaignBudgetResponse:
|
|
1641
|
-
type: object
|
|
1642
|
-
required: [data, meta]
|
|
1643
|
-
properties:
|
|
1644
|
-
data:
|
|
1645
|
-
$ref: '#/components/schemas/IncreaseCampaignBudgetData'
|
|
1646
|
-
meta:
|
|
1647
|
-
$ref: '#/components/schemas/Meta'
|
|
1648
|
-
|
|
1649
|
-
DecreaseCampaignBudgetRequest:
|
|
1650
|
-
type: object
|
|
1651
|
-
required: [targetDailyBudget]
|
|
1652
|
-
properties:
|
|
1653
|
-
targetDailyBudget:
|
|
1654
|
-
type: number
|
|
1655
|
-
minimum: 10
|
|
1656
3017
|
description: |
|
|
1657
|
-
|
|
1658
|
-
|
|
1659
|
-
|
|
1660
|
-
|
|
1661
|
-
|
|
1662
|
-
|
|
1663
|
-
|
|
1664
|
-
required: [campaignId, mode, targetDailyBudget, accepted]
|
|
1665
|
-
properties:
|
|
1666
|
-
campaignId:
|
|
1667
|
-
type: string
|
|
1668
|
-
mode:
|
|
1669
|
-
$ref: '#/components/schemas/BudgetDecreaseMode'
|
|
1670
|
-
targetDailyBudget:
|
|
1671
|
-
type: number
|
|
1672
|
-
accepted:
|
|
1673
|
-
type: boolean
|
|
1674
|
-
enum: [true]
|
|
3018
|
+
Clicks on "Continue with Spotify" on the landing page — outbound
|
|
3019
|
+
clicks to Spotify. Null if not tracked for this soundlink type.
|
|
3020
|
+
streams:
|
|
3021
|
+
type: integer
|
|
3022
|
+
description: Attributed Spotify streams (sum of country-day rows).
|
|
3023
|
+
listeners:
|
|
3024
|
+
type: integer
|
|
1675
3025
|
description: |
|
|
1676
|
-
|
|
1677
|
-
|
|
1678
|
-
|
|
3026
|
+
Sum of country-day `new_listeners` from the mart (first-play
|
|
3027
|
+
attributed listeners). Not period-unique across days/countries,
|
|
3028
|
+
and not equal to summing breakdown `listeners` (new + returning).
|
|
3029
|
+
followers:
|
|
3030
|
+
type: integer
|
|
3031
|
+
description: Attributed Spotify artist follower gains in the period.
|
|
3032
|
+
streams_per_listener:
|
|
3033
|
+
type: number
|
|
3034
|
+
description: streams / listeners. Zero if listeners is zero.
|
|
3035
|
+
ctr_lp:
|
|
1679
3036
|
type: number
|
|
1680
3037
|
nullable: true
|
|
1681
3038
|
description: |
|
|
1682
|
-
|
|
1683
|
-
|
|
3039
|
+
Landing page click-through rate (link_clicks / views). Computed
|
|
3040
|
+
against landing page views, not ad impressions — do not combine
|
|
3041
|
+
with `ctr_linkclick` from campaign metrics. Null if views is zero
|
|
3042
|
+
or link_clicks is null.
|
|
1684
3043
|
|
|
1685
|
-
|
|
3044
|
+
SoundlinkMetricsOverviewResponse:
|
|
1686
3045
|
type: object
|
|
1687
3046
|
required: [data, meta]
|
|
1688
3047
|
properties:
|
|
1689
3048
|
data:
|
|
1690
|
-
$ref: '#/components/schemas/
|
|
3049
|
+
$ref: '#/components/schemas/SoundlinkMetricsOverview'
|
|
1691
3050
|
meta:
|
|
1692
3051
|
$ref: '#/components/schemas/Meta'
|
|
1693
3052
|
|
|
1694
|
-
|
|
1695
|
-
|
|
1696
|
-
MetricsOverview:
|
|
3053
|
+
SoundlinkDailyRow:
|
|
1697
3054
|
type: object
|
|
1698
3055
|
description: |
|
|
1699
|
-
|
|
1700
|
-
|
|
1701
|
-
|
|
3056
|
+
One row of the `soundlink_daily` v1.0 schema.
|
|
3057
|
+
Primary key: `(provider, account_id, report_date, soundlink_id)`.
|
|
3058
|
+
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
3059
|
+
Values for a given `report_date` may be revised for up to 7 days after
|
|
3060
|
+
the date closes due to delayed Spotify playback events.
|
|
3061
|
+
Rows are aggregated across countries (no `country_code` in v1.0) and
|
|
3062
|
+
contain no financial fields.
|
|
1702
3063
|
required:
|
|
1703
|
-
|
|
1704
|
-
|
|
1705
|
-
|
|
1706
|
-
|
|
1707
|
-
|
|
1708
|
-
|
|
1709
|
-
|
|
1710
|
-
|
|
1711
|
-
|
|
1712
|
-
|
|
1713
|
-
|
|
1714
|
-
|
|
3064
|
+
- provider
|
|
3065
|
+
- account_id
|
|
3066
|
+
- schema_version
|
|
3067
|
+
- report_date
|
|
3068
|
+
- report_date_timezone
|
|
3069
|
+
- exported_at
|
|
3070
|
+
- soundlink_id
|
|
3071
|
+
- soundlink_name
|
|
3072
|
+
- soundlink_target_type
|
|
3073
|
+
- views
|
|
3074
|
+
- streams
|
|
3075
|
+
- listeners
|
|
3076
|
+
- followers
|
|
3077
|
+
- streams_per_listener
|
|
1715
3078
|
properties:
|
|
1716
|
-
|
|
3079
|
+
provider:
|
|
3080
|
+
type: string
|
|
3081
|
+
enum: [soundlink]
|
|
3082
|
+
description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
|
|
3083
|
+
account_id:
|
|
3084
|
+
type: string
|
|
3085
|
+
description: Soundlink organization ID (UUID).
|
|
3086
|
+
schema_version:
|
|
3087
|
+
type: string
|
|
3088
|
+
description: Schema version. Pin your ingest pipeline to this value.
|
|
3089
|
+
example: '1.0'
|
|
3090
|
+
report_date:
|
|
3091
|
+
type: string
|
|
3092
|
+
format: date
|
|
3093
|
+
description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
|
|
3094
|
+
report_date_timezone:
|
|
3095
|
+
type: string
|
|
3096
|
+
enum: [UTC]
|
|
3097
|
+
description: Always `UTC`.
|
|
3098
|
+
exported_at:
|
|
3099
|
+
type: string
|
|
3100
|
+
format: date-time
|
|
3101
|
+
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
3102
|
+
soundlink_id:
|
|
3103
|
+
type: string
|
|
3104
|
+
description: Unique ID of this soundlink.
|
|
3105
|
+
example: V1StGXR8_Z5jdHi6B-myT
|
|
3106
|
+
soundlink_name:
|
|
3107
|
+
type: string
|
|
3108
|
+
description: Human-readable soundlink name.
|
|
3109
|
+
soundlink_target_type:
|
|
3110
|
+
type: string
|
|
3111
|
+
nullable: true
|
|
3112
|
+
enum: [track, playlist]
|
|
3113
|
+
description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
|
|
3114
|
+
soundlink_target_isrc:
|
|
3115
|
+
type: string
|
|
3116
|
+
nullable: true
|
|
3117
|
+
description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3118
|
+
soundlink_target_spotify_track_id:
|
|
3119
|
+
type: string
|
|
3120
|
+
nullable: true
|
|
3121
|
+
description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3122
|
+
soundlink_target_playlist_id:
|
|
3123
|
+
type: string
|
|
3124
|
+
nullable: true
|
|
3125
|
+
description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
|
|
3126
|
+
views:
|
|
1717
3127
|
type: integer
|
|
1718
|
-
description:
|
|
3128
|
+
description: Soundlink landing page views on this day.
|
|
3129
|
+
link_clicks:
|
|
3130
|
+
type: integer
|
|
3131
|
+
nullable: true
|
|
3132
|
+
description: |
|
|
3133
|
+
Clicks on "Continue with Spotify" on the landing page — outbound
|
|
3134
|
+
clicks to Spotify. Null if not tracked for this soundlink type.
|
|
1719
3135
|
streams:
|
|
1720
3136
|
type: integer
|
|
1721
|
-
description:
|
|
1722
|
-
|
|
3137
|
+
description: |
|
|
3138
|
+
Spotify streams attributed to this soundlink on this day:
|
|
3139
|
+
`new_listener_streams + returning_listener_streams`. Observed
|
|
3140
|
+
Spotify-side events, not modelled estimates. Safe to sum within a
|
|
3141
|
+
day; summing across days counts repeat listens.
|
|
3142
|
+
listeners:
|
|
3143
|
+
type: integer
|
|
3144
|
+
description: |
|
|
3145
|
+
Unique Spotify listeners attributed to this soundlink on this day:
|
|
3146
|
+
`new_listeners + returning_listeners`. **Do not sum across days** —
|
|
3147
|
+
the same listener can appear on multiple `report_date` rows.
|
|
3148
|
+
new_listeners:
|
|
1723
3149
|
type: integer
|
|
1724
|
-
|
|
1725
|
-
|
|
3150
|
+
nullable: true
|
|
3151
|
+
description: Unique listeners whose first play via this soundlink occurred on `report_date`.
|
|
3152
|
+
returning_listeners:
|
|
1726
3153
|
type: integer
|
|
1727
3154
|
nullable: true
|
|
1728
|
-
description:
|
|
1729
|
-
|
|
3155
|
+
description: Unique listeners who played on `report_date` but whose first play was on an earlier date.
|
|
3156
|
+
new_listener_streams:
|
|
1730
3157
|
type: integer
|
|
1731
3158
|
nullable: true
|
|
1732
|
-
description:
|
|
1733
|
-
|
|
3159
|
+
description: Stream count from new listeners on `report_date`.
|
|
3160
|
+
returning_listener_streams:
|
|
1734
3161
|
type: integer
|
|
1735
3162
|
nullable: true
|
|
1736
|
-
description:
|
|
1737
|
-
|
|
1738
|
-
type:
|
|
1739
|
-
description:
|
|
1740
|
-
spend_total:
|
|
1741
|
-
type: number
|
|
1742
|
-
description: Total billed by Soundlink (spend_media + fees). USD.
|
|
1743
|
-
fees:
|
|
1744
|
-
type: number
|
|
1745
|
-
description: Soundlink service fee (spend_total - spend_media). USD.
|
|
1746
|
-
currency:
|
|
1747
|
-
type: string
|
|
1748
|
-
description: Currency for spend fields. Currently always `USD`.
|
|
1749
|
-
cpl:
|
|
1750
|
-
type: number
|
|
1751
|
-
description: Cost per listener (spend_media / listeners).
|
|
1752
|
-
cpf:
|
|
1753
|
-
type: number
|
|
1754
|
-
description: Cost per follower (spend_media / followers).
|
|
3163
|
+
description: Stream count from returning listeners on `report_date`.
|
|
3164
|
+
followers:
|
|
3165
|
+
type: integer
|
|
3166
|
+
description: Spotify artist follower gains attributed to this soundlink on this day.
|
|
1755
3167
|
streams_per_listener:
|
|
1756
3168
|
type: number
|
|
1757
|
-
description: streams / listeners. Zero if listeners is zero.
|
|
3169
|
+
description: streams / listeners for this row. Zero if listeners is zero.
|
|
3170
|
+
ctr_lp:
|
|
3171
|
+
type: number
|
|
3172
|
+
nullable: true
|
|
3173
|
+
description: |
|
|
3174
|
+
Landing page click-through rate (link_clicks / views). Computed
|
|
3175
|
+
against landing page views, not ad impressions — do not combine
|
|
3176
|
+
with `ctr_linkclick` from `campaign_country_daily`. Null if views
|
|
3177
|
+
is zero or link_clicks is null.
|
|
1758
3178
|
|
|
1759
|
-
|
|
3179
|
+
SoundlinkTimeseriesResponse:
|
|
1760
3180
|
type: object
|
|
1761
3181
|
required: [data, meta]
|
|
1762
3182
|
properties:
|
|
1763
3183
|
data:
|
|
1764
|
-
|
|
3184
|
+
type: object
|
|
3185
|
+
required: [schemaVersion, items, pagination]
|
|
3186
|
+
properties:
|
|
3187
|
+
schemaVersion:
|
|
3188
|
+
type: string
|
|
3189
|
+
description: Version of the `soundlink_daily` row schema. Pin your ingest pipeline to this.
|
|
3190
|
+
example: '1.0'
|
|
3191
|
+
items:
|
|
3192
|
+
type: array
|
|
3193
|
+
items:
|
|
3194
|
+
$ref: '#/components/schemas/SoundlinkDailyRow'
|
|
3195
|
+
pagination:
|
|
3196
|
+
$ref: '#/components/schemas/Pagination'
|
|
1765
3197
|
meta:
|
|
1766
3198
|
$ref: '#/components/schemas/Meta'
|
|
1767
3199
|
|
|
1768
|
-
|
|
3200
|
+
SoundlinkCountryDailyRow:
|
|
1769
3201
|
type: object
|
|
1770
3202
|
description: |
|
|
1771
|
-
One row of the `
|
|
1772
|
-
Primary key: `(provider, account_id, report_date,
|
|
3203
|
+
One row of the `soundlink_country_daily` v1.0 schema.
|
|
3204
|
+
Primary key: `(provider, account_id, report_date, soundlink_id, country_code)`.
|
|
1773
3205
|
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
1774
3206
|
Values for a given `report_date` may be revised for up to 7 days after
|
|
1775
|
-
the date closes due to delayed
|
|
3207
|
+
the date closes due to delayed Spotify playback events.
|
|
3208
|
+
Rows contain no financial fields.
|
|
1776
3209
|
required:
|
|
1777
3210
|
- provider
|
|
1778
3211
|
- account_id
|
|
@@ -1780,22 +3213,15 @@ components:
|
|
|
1780
3213
|
- report_date
|
|
1781
3214
|
- report_date_timezone
|
|
1782
3215
|
- exported_at
|
|
1783
|
-
-
|
|
1784
|
-
-
|
|
1785
|
-
-
|
|
3216
|
+
- soundlink_id
|
|
3217
|
+
- soundlink_name
|
|
3218
|
+
- soundlink_target_type
|
|
1786
3219
|
- country_code
|
|
3220
|
+
- views
|
|
1787
3221
|
- streams
|
|
1788
3222
|
- listeners
|
|
1789
3223
|
- followers
|
|
1790
3224
|
- streams_per_listener
|
|
1791
|
-
- spend_media
|
|
1792
|
-
- spend_total
|
|
1793
|
-
- fees
|
|
1794
|
-
- currency
|
|
1795
|
-
- currency_account
|
|
1796
|
-
- cpl
|
|
1797
|
-
- cpf
|
|
1798
|
-
- cost_per_result
|
|
1799
3225
|
properties:
|
|
1800
3226
|
provider:
|
|
1801
3227
|
type: string
|
|
@@ -1820,99 +3246,88 @@ components:
|
|
|
1820
3246
|
type: string
|
|
1821
3247
|
format: date-time
|
|
1822
3248
|
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
1823
|
-
|
|
3249
|
+
soundlink_id:
|
|
1824
3250
|
type: string
|
|
1825
|
-
description:
|
|
1826
|
-
|
|
3251
|
+
description: Unique ID of this soundlink.
|
|
3252
|
+
example: V1StGXR8_Z5jdHi6B-myT
|
|
3253
|
+
soundlink_name:
|
|
1827
3254
|
type: string
|
|
1828
|
-
description: Human-readable
|
|
1829
|
-
|
|
3255
|
+
description: Human-readable soundlink name.
|
|
3256
|
+
soundlink_target_type:
|
|
1830
3257
|
type: string
|
|
1831
3258
|
nullable: true
|
|
1832
3259
|
enum: [track, playlist]
|
|
1833
|
-
description: Whether this
|
|
1834
|
-
|
|
3260
|
+
description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
|
|
3261
|
+
soundlink_target_isrc:
|
|
1835
3262
|
type: string
|
|
1836
3263
|
nullable: true
|
|
1837
|
-
description: ISRC of the promoted track. Populated when `
|
|
1838
|
-
|
|
3264
|
+
description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3265
|
+
soundlink_target_spotify_track_id:
|
|
1839
3266
|
type: string
|
|
1840
3267
|
nullable: true
|
|
1841
|
-
description: Spotify track ID of the promoted track. Populated when `
|
|
1842
|
-
|
|
3268
|
+
description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3269
|
+
soundlink_target_playlist_id:
|
|
1843
3270
|
type: string
|
|
1844
3271
|
nullable: true
|
|
1845
|
-
description: Spotify playlist ID. Populated when `
|
|
3272
|
+
description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
|
|
1846
3273
|
country_code:
|
|
1847
3274
|
type: string
|
|
1848
3275
|
description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
|
|
1849
|
-
|
|
1850
|
-
type: integer
|
|
1851
|
-
nullable: true
|
|
1852
|
-
description: Total Meta ad impressions served in this country on this day.
|
|
1853
|
-
ad_clicks:
|
|
3276
|
+
views:
|
|
1854
3277
|
type: integer
|
|
1855
|
-
|
|
1856
|
-
description: Total clicks on the Meta ad (all click types). Use `ctr_adclick` for ad-level CTR.
|
|
3278
|
+
description: Soundlink landing page views in this country on this day.
|
|
1857
3279
|
link_clicks:
|
|
1858
3280
|
type: integer
|
|
1859
3281
|
nullable: true
|
|
1860
|
-
description:
|
|
3282
|
+
description: |
|
|
3283
|
+
Clicks on "Continue with Spotify" on the landing page — outbound
|
|
3284
|
+
clicks to Spotify. Null if not tracked for this soundlink type.
|
|
1861
3285
|
streams:
|
|
1862
3286
|
type: integer
|
|
1863
|
-
description:
|
|
3287
|
+
description: |
|
|
3288
|
+
Spotify streams attributed to this soundlink in this country on this
|
|
3289
|
+
day: `new_listener_streams + returning_listener_streams`. Observed
|
|
3290
|
+
Spotify-side events, not modelled estimates. Safe to sum within a
|
|
3291
|
+
day; summing across days counts repeat listens.
|
|
1864
3292
|
listeners:
|
|
1865
3293
|
type: integer
|
|
1866
|
-
description:
|
|
3294
|
+
description: |
|
|
3295
|
+
Unique Spotify listeners attributed to this soundlink in this
|
|
3296
|
+
country on this day: `new_listeners + returning_listeners`.
|
|
3297
|
+
**Do not sum across days** — the same listener can appear on
|
|
3298
|
+
multiple `report_date` rows.
|
|
3299
|
+
new_listeners:
|
|
3300
|
+
type: integer
|
|
3301
|
+
nullable: true
|
|
3302
|
+
description: Unique listeners whose first play via this soundlink occurred on `report_date` in this country.
|
|
3303
|
+
returning_listeners:
|
|
3304
|
+
type: integer
|
|
3305
|
+
nullable: true
|
|
3306
|
+
description: Unique listeners who played on `report_date` in this country but whose first play was on an earlier date.
|
|
3307
|
+
new_listener_streams:
|
|
3308
|
+
type: integer
|
|
3309
|
+
nullable: true
|
|
3310
|
+
description: Stream count from new listeners on `report_date` in this country.
|
|
3311
|
+
returning_listener_streams:
|
|
3312
|
+
type: integer
|
|
3313
|
+
nullable: true
|
|
3314
|
+
description: Stream count from returning listeners on `report_date` in this country.
|
|
1867
3315
|
followers:
|
|
1868
3316
|
type: integer
|
|
1869
|
-
description: Spotify artist follower gains attributed to this
|
|
3317
|
+
description: Spotify artist follower gains attributed to this soundlink in this country on this day.
|
|
1870
3318
|
streams_per_listener:
|
|
1871
3319
|
type: number
|
|
1872
3320
|
description: streams / listeners for this row. Zero if listeners is zero.
|
|
1873
|
-
|
|
1874
|
-
type: number
|
|
1875
|
-
description: Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In `currency`.
|
|
1876
|
-
spend_total:
|
|
1877
|
-
type: number
|
|
1878
|
-
description: Total billed by Soundlink (spend_media + fees). Computed as `spend_media / (1 - fee_pct)`.
|
|
1879
|
-
fees:
|
|
1880
|
-
type: number
|
|
1881
|
-
description: Soundlink service fee (spend_total - spend_media).
|
|
1882
|
-
currency:
|
|
1883
|
-
type: string
|
|
1884
|
-
description: Currency for spend fields. Currently always `USD`.
|
|
1885
|
-
currency_account:
|
|
1886
|
-
type: string
|
|
1887
|
-
description: Account billing currency. Currently always `USD`. Will differ from `currency` once EUR delivery is available.
|
|
1888
|
-
cpl:
|
|
1889
|
-
type: number
|
|
1890
|
-
description: Cost per listener (spend_media / listeners). Zero if listeners is zero.
|
|
1891
|
-
cpf:
|
|
3321
|
+
ctr_lp:
|
|
1892
3322
|
type: number
|
|
1893
|
-
description: Cost per follower (spend_media / followers). Zero if followers is zero.
|
|
1894
|
-
cpc_linkclick:
|
|
1895
|
-
type: number
|
|
1896
|
-
nullable: true
|
|
1897
|
-
description: Cost per outbound click (spend_media / link_clicks). Null if link_clicks is null or zero.
|
|
1898
|
-
ctr_linkclick:
|
|
1899
|
-
type: number
|
|
1900
|
-
nullable: true
|
|
1901
|
-
description: Outbound CTR (link_clicks / impressions). Null if impressions is null or zero.
|
|
1902
|
-
ctr_adclick:
|
|
1903
|
-
type: number
|
|
1904
|
-
nullable: true
|
|
1905
|
-
description: Meta ad CTR (ad_clicks / impressions). Null if impressions is null or zero.
|
|
1906
|
-
cost_per_result:
|
|
1907
|
-
type: number
|
|
1908
|
-
description: Cost per primary campaign result. Currently equivalent to `cpf` (cost per follower). See `result_type`.
|
|
1909
|
-
result_type:
|
|
1910
|
-
type: string
|
|
1911
3323
|
nullable: true
|
|
1912
|
-
|
|
1913
|
-
|
|
3324
|
+
description: |
|
|
3325
|
+
Landing page click-through rate (link_clicks / views). Computed
|
|
3326
|
+
against landing page views, not ad impressions — do not combine
|
|
3327
|
+
with `ctr_linkclick` from `campaign_country_daily`. Null if views
|
|
3328
|
+
is zero or link_clicks is null.
|
|
1914
3329
|
|
|
1915
|
-
|
|
3330
|
+
SoundlinkBreakdownResponse:
|
|
1916
3331
|
type: object
|
|
1917
3332
|
required: [data, meta]
|
|
1918
3333
|
properties:
|
|
@@ -1922,27 +3337,48 @@ components:
|
|
|
1922
3337
|
properties:
|
|
1923
3338
|
schemaVersion:
|
|
1924
3339
|
type: string
|
|
1925
|
-
description: Version of the `
|
|
3340
|
+
description: Version of the `soundlink_country_daily` row schema. Pin your ingest pipeline to this.
|
|
1926
3341
|
example: '1.0'
|
|
1927
3342
|
items:
|
|
1928
3343
|
type: array
|
|
1929
3344
|
items:
|
|
1930
|
-
$ref: '#/components/schemas/
|
|
3345
|
+
$ref: '#/components/schemas/SoundlinkCountryDailyRow'
|
|
1931
3346
|
pagination:
|
|
1932
3347
|
$ref: '#/components/schemas/Pagination'
|
|
1933
3348
|
meta:
|
|
1934
3349
|
$ref: '#/components/schemas/Meta'
|
|
1935
3350
|
|
|
1936
|
-
|
|
3351
|
+
SoundlinkEngagementResponse:
|
|
3352
|
+
type: object
|
|
3353
|
+
required: [data, meta]
|
|
3354
|
+
properties:
|
|
3355
|
+
data:
|
|
3356
|
+
type: object
|
|
3357
|
+
required: [schemaVersion, items, pagination]
|
|
3358
|
+
properties:
|
|
3359
|
+
schemaVersion:
|
|
3360
|
+
type: string
|
|
3361
|
+
description: Version of the `soundlink_engagement_daily` row schema. Pin your ingest pipeline to this.
|
|
3362
|
+
example: '1.0'
|
|
3363
|
+
items:
|
|
3364
|
+
type: array
|
|
3365
|
+
items:
|
|
3366
|
+
$ref: '#/components/schemas/SoundlinkEngagementDailyRow'
|
|
3367
|
+
pagination:
|
|
3368
|
+
$ref: '#/components/schemas/Pagination'
|
|
3369
|
+
meta:
|
|
3370
|
+
$ref: '#/components/schemas/Meta'
|
|
1937
3371
|
|
|
1938
|
-
|
|
3372
|
+
SoundlinkEngagementDailyRow:
|
|
1939
3373
|
type: object
|
|
1940
3374
|
description: |
|
|
1941
|
-
One row of the `
|
|
1942
|
-
Primary key: `(provider, account_id, report_date,
|
|
3375
|
+
One row of the `soundlink_engagement_daily` v1.0 schema.
|
|
3376
|
+
Primary key: `(provider, account_id, report_date, soundlink_id, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
1943
3377
|
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
1944
3378
|
Values for a given `report_date` may be revised for up to 7 days after
|
|
1945
3379
|
the date closes due to delayed Spotify playback events.
|
|
3380
|
+
No `status` field: soundlinks do not store per-day lifecycle history.
|
|
3381
|
+
No financial fields.
|
|
1946
3382
|
required:
|
|
1947
3383
|
- provider
|
|
1948
3384
|
- account_id
|
|
@@ -1950,10 +3386,9 @@ components:
|
|
|
1950
3386
|
- report_date
|
|
1951
3387
|
- report_date_timezone
|
|
1952
3388
|
- exported_at
|
|
1953
|
-
-
|
|
1954
|
-
-
|
|
1955
|
-
-
|
|
1956
|
-
- status
|
|
3389
|
+
- soundlink_id
|
|
3390
|
+
- soundlink_name
|
|
3391
|
+
- soundlink_target_type
|
|
1957
3392
|
- engagement_context
|
|
1958
3393
|
- country_code
|
|
1959
3394
|
- engaged_spotify_track_id
|
|
@@ -1989,44 +3424,37 @@ components:
|
|
|
1989
3424
|
type: string
|
|
1990
3425
|
format: date-time
|
|
1991
3426
|
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
1992
|
-
|
|
3427
|
+
soundlink_id:
|
|
1993
3428
|
type: string
|
|
1994
|
-
description:
|
|
1995
|
-
|
|
3429
|
+
description: Unique ID of this soundlink.
|
|
3430
|
+
example: V1StGXR8_Z5jdHi6B-myT
|
|
3431
|
+
soundlink_name:
|
|
1996
3432
|
type: string
|
|
1997
|
-
description: Human-readable
|
|
1998
|
-
|
|
3433
|
+
description: Human-readable soundlink name.
|
|
3434
|
+
soundlink_target_type:
|
|
1999
3435
|
type: string
|
|
2000
3436
|
nullable: true
|
|
2001
3437
|
enum: [track, playlist]
|
|
2002
|
-
description: Whether this
|
|
2003
|
-
|
|
3438
|
+
description: Whether this soundlink promotes a track or playlist. `null` if undetermined.
|
|
3439
|
+
soundlink_target_isrc:
|
|
2004
3440
|
type: string
|
|
2005
3441
|
nullable: true
|
|
2006
|
-
description: ISRC of the promoted track. Populated when `
|
|
2007
|
-
|
|
3442
|
+
description: ISRC of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3443
|
+
soundlink_target_spotify_track_id:
|
|
2008
3444
|
type: string
|
|
2009
3445
|
nullable: true
|
|
2010
|
-
description: Spotify track ID of the promoted track. Populated when `
|
|
2011
|
-
|
|
3446
|
+
description: Spotify track ID of the promoted track. Populated when `soundlink_target_type = track`; otherwise `null`.
|
|
3447
|
+
soundlink_target_playlist_id:
|
|
2012
3448
|
type: string
|
|
2013
3449
|
nullable: true
|
|
2014
|
-
description: Spotify playlist ID. Populated when `
|
|
2015
|
-
status:
|
|
2016
|
-
type: string
|
|
2017
|
-
enum: [active, ended, scheduled]
|
|
2018
|
-
description: |
|
|
2019
|
-
Campaign lifecycle status on `report_date`.
|
|
2020
|
-
`active` = campaign was running; `ended` = campaign had ended or was refunded;
|
|
2021
|
-
`scheduled` = `report_date` is before campaign start.
|
|
2022
|
-
Post-campaign rows will have `status = ended`.
|
|
3450
|
+
description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
|
|
2023
3451
|
engagement_context:
|
|
2024
3452
|
type: string
|
|
2025
3453
|
enum: [catalog, playlist]
|
|
2026
3454
|
description: |
|
|
2027
|
-
Which
|
|
2028
|
-
`catalog
|
|
2029
|
-
`playlist
|
|
3455
|
+
Which section this row belongs to.
|
|
3456
|
+
`catalog`: plays of the promoted track and same-artist catalog tracks (track soundlinks).
|
|
3457
|
+
`playlist`: per-track performance inside the promoted playlist (playlist soundlinks).
|
|
2030
3458
|
country_code:
|
|
2031
3459
|
type: string
|
|
2032
3460
|
description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
|
|
@@ -2035,13 +3463,11 @@ components:
|
|
|
2035
3463
|
type: string
|
|
2036
3464
|
nullable: true
|
|
2037
3465
|
description: |
|
|
2038
|
-
ISRC of the track that received listens. May differ from `
|
|
3466
|
+
ISRC of the track that received listens. May differ from `soundlink_target_isrc`
|
|
2039
3467
|
for catalog spillover rows. `null` if ISRC could not be resolved.
|
|
2040
3468
|
engaged_spotify_track_id:
|
|
2041
3469
|
type: string
|
|
2042
|
-
description:
|
|
2043
|
-
Stable track identifier used in the primary key. Currently this is the
|
|
2044
|
-
Spotify track ID for the engaged track.
|
|
3470
|
+
description: Spotify track ID of the engaged track. Part of the primary key.
|
|
2045
3471
|
example: 4cOdK2wGLETKBW3PvgPWqT
|
|
2046
3472
|
engaged_track_name:
|
|
2047
3473
|
type: string
|
|
@@ -2052,14 +3478,11 @@ components:
|
|
|
2052
3478
|
minimum: 1
|
|
2053
3479
|
description: |
|
|
2054
3480
|
1-based slot of the engaged track on the promoted playlist for `report_date` (1 = top).
|
|
2055
|
-
Populated only when `engagement_context = playlist
|
|
2056
|
-
`null` for catalog rows; before the day's crawl completes (current UTC day is often null until later morning UTC);
|
|
2057
|
-
when the track was not listed or could not be matched to that day's crawl; or while historical backfill is still catching up.
|
|
2058
|
-
Field is beta until historical backfill finishes. Treat `null` as unavailable — not an error.
|
|
3481
|
+
Populated only when `engagement_context = playlist`. Treat `null` as unavailable, not an error.
|
|
2059
3482
|
new_listeners:
|
|
2060
3483
|
type: integer
|
|
2061
3484
|
minimum: 0
|
|
2062
|
-
description: Unique listeners whose first play of this track
|
|
3485
|
+
description: Unique listeners whose first play of this track via this soundlink occurred on `report_date`.
|
|
2063
3486
|
returning_listeners:
|
|
2064
3487
|
type: integer
|
|
2065
3488
|
minimum: 0
|
|
@@ -2092,16 +3515,44 @@ components:
|
|
|
2092
3515
|
|
|
2093
3516
|
VideoImportRequest:
|
|
2094
3517
|
type: object
|
|
2095
|
-
|
|
3518
|
+
description: |
|
|
3519
|
+
Provide either `url` (single) or `videos` (batch of 1–5). Do not send both.
|
|
2096
3520
|
properties:
|
|
2097
3521
|
url:
|
|
2098
3522
|
type: string
|
|
2099
3523
|
format: uri
|
|
2100
|
-
description: Public HTTPS URL to an MP4 file (max 50 MB).
|
|
3524
|
+
description: Public HTTPS URL to an MP4 file (max 50 MB). Mutually exclusive with `videos`.
|
|
3525
|
+
videos:
|
|
3526
|
+
type: array
|
|
3527
|
+
minItems: 1
|
|
3528
|
+
maxItems: 5
|
|
3529
|
+
description: Batch of video URLs. Mutually exclusive with `url`.
|
|
3530
|
+
items:
|
|
3531
|
+
type: object
|
|
3532
|
+
required: [url]
|
|
3533
|
+
properties:
|
|
3534
|
+
url:
|
|
3535
|
+
type: string
|
|
3536
|
+
format: uri
|
|
3537
|
+
description: Public HTTPS URL to an MP4 file (max 50 MB).
|
|
2101
3538
|
|
|
2102
3539
|
VideoImportStatus:
|
|
2103
3540
|
type: string
|
|
2104
|
-
enum: [processing, ready, failed]
|
|
3541
|
+
enum: [processing, ready, failed, partial]
|
|
3542
|
+
|
|
3543
|
+
VideoImportCounts:
|
|
3544
|
+
type: object
|
|
3545
|
+
required: [total, ready, failed]
|
|
3546
|
+
properties:
|
|
3547
|
+
total:
|
|
3548
|
+
type: integer
|
|
3549
|
+
description: Videos admitted in the session
|
|
3550
|
+
ready:
|
|
3551
|
+
type: integer
|
|
3552
|
+
description: Ingested successfully
|
|
3553
|
+
failed:
|
|
3554
|
+
type: integer
|
|
3555
|
+
description: Ingestion failures (download failures fail the whole session in this phase)
|
|
2105
3556
|
|
|
2106
3557
|
VideoImportStartData:
|
|
2107
3558
|
type: object
|
|
@@ -2113,6 +3564,9 @@ components:
|
|
|
2113
3564
|
description: Upload session ID for status polling
|
|
2114
3565
|
status:
|
|
2115
3566
|
$ref: '#/components/schemas/VideoImportStatus'
|
|
3567
|
+
count:
|
|
3568
|
+
type: integer
|
|
3569
|
+
description: Number of videos accepted for import
|
|
2116
3570
|
videoId:
|
|
2117
3571
|
type: string
|
|
2118
3572
|
format: uuid
|
|
@@ -2141,11 +3595,40 @@ components:
|
|
|
2141
3595
|
type: string
|
|
2142
3596
|
format: uuid
|
|
2143
3597
|
nullable: true
|
|
2144
|
-
description:
|
|
3598
|
+
description: Present for single-URL sessions when ready or failed after ingest
|
|
3599
|
+
videoIds:
|
|
3600
|
+
type: array
|
|
3601
|
+
items:
|
|
3602
|
+
type: string
|
|
3603
|
+
format: uuid
|
|
3604
|
+
description: Ready video IDs for batch sessions (`count > 1`)
|
|
3605
|
+
counts:
|
|
3606
|
+
$ref: '#/components/schemas/VideoImportCounts'
|
|
2145
3607
|
error:
|
|
2146
|
-
|
|
3608
|
+
allOf:
|
|
3609
|
+
- $ref: '#/components/schemas/VideoImportStatusError'
|
|
2147
3610
|
nullable: true
|
|
2148
|
-
description:
|
|
3611
|
+
description: Present when status is failed
|
|
3612
|
+
|
|
3613
|
+
VideoImportStatusError:
|
|
3614
|
+
type: object
|
|
3615
|
+
required: [code, message]
|
|
3616
|
+
properties:
|
|
3617
|
+
code:
|
|
3618
|
+
type: string
|
|
3619
|
+
enum:
|
|
3620
|
+
- video_too_large
|
|
3621
|
+
- invalid_video_content_type
|
|
3622
|
+
- storage_limit_exceeded
|
|
3623
|
+
- no_videos_imported
|
|
3624
|
+
- duplicate_videos
|
|
3625
|
+
- import_failed
|
|
3626
|
+
description: >
|
|
3627
|
+
Machine-readable failure code. Legacy sessions without a stored
|
|
3628
|
+
code fall back to import_failed.
|
|
3629
|
+
message:
|
|
3630
|
+
type: string
|
|
3631
|
+
description: Human-readable failure message
|
|
2149
3632
|
|
|
2150
3633
|
VideoImportStatusResponse:
|
|
2151
3634
|
type: object
|
|
@@ -2204,7 +3687,10 @@ components:
|
|
|
2204
3687
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
2205
3688
|
|
|
2206
3689
|
Unauthorized:
|
|
2207
|
-
description:
|
|
3690
|
+
description: |
|
|
3691
|
+
Missing or invalid credentials. Covers missing/malformed API keys,
|
|
3692
|
+
invalid or expired OAuth access tokens, and revoked API keys.
|
|
3693
|
+
`x-api-key` is not accepted and is ignored if sent.
|
|
2208
3694
|
headers:
|
|
2209
3695
|
Retry-After:
|
|
2210
3696
|
schema:
|
|
@@ -2219,7 +3705,14 @@ components:
|
|
|
2219
3705
|
value:
|
|
2220
3706
|
error:
|
|
2221
3707
|
code: invalid_api_key
|
|
2222
|
-
message: 'Missing
|
|
3708
|
+
message: 'Missing credentials. Send Authorization: Bearer.'
|
|
3709
|
+
meta:
|
|
3710
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
3711
|
+
invalid_token:
|
|
3712
|
+
value:
|
|
3713
|
+
error:
|
|
3714
|
+
code: invalid_token
|
|
3715
|
+
message: 'OAuth access token is invalid or expired.'
|
|
2223
3716
|
meta:
|
|
2224
3717
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
2225
3718
|
api_key_revoked:
|
|
@@ -2231,17 +3724,28 @@ components:
|
|
|
2231
3724
|
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
2232
3725
|
|
|
2233
3726
|
Forbidden:
|
|
2234
|
-
description:
|
|
3727
|
+
description: |
|
|
3728
|
+
Authenticated but not allowed: missing required scope, or OAuth access
|
|
3729
|
+
disabled for the organization (`access_denied`).
|
|
2235
3730
|
content:
|
|
2236
3731
|
application/json:
|
|
2237
3732
|
schema:
|
|
2238
3733
|
$ref: '#/components/schemas/ErrorResponse'
|
|
2239
|
-
|
|
2240
|
-
|
|
2241
|
-
|
|
2242
|
-
|
|
2243
|
-
|
|
2244
|
-
|
|
3734
|
+
examples:
|
|
3735
|
+
insufficient_scope:
|
|
3736
|
+
value:
|
|
3737
|
+
error:
|
|
3738
|
+
code: insufficient_scope
|
|
3739
|
+
message: 'This token does not have the metrics:read scope.'
|
|
3740
|
+
meta:
|
|
3741
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
3742
|
+
access_denied:
|
|
3743
|
+
value:
|
|
3744
|
+
error:
|
|
3745
|
+
code: access_denied
|
|
3746
|
+
message: 'OAuth access is not enabled for this organization.'
|
|
3747
|
+
meta:
|
|
3748
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
2245
3749
|
|
|
2246
3750
|
CreateCampaignForbidden:
|
|
2247
3751
|
description: |
|