soundlink 1.0.0 → 1.1.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 +13 -0
- package/LICENSE +21 -0
- package/README.md +216 -0
- package/dist/cjs/index.cjs +527 -0
- package/dist/cjs/index.cjs.map +1 -0
- package/dist/esm/index.d.ts +269 -0
- package/dist/esm/index.js +513 -0
- package/dist/esm/index.js.map +1 -0
- package/openapi/soundlink-public-api-v1.yaml +1289 -0
- package/package.json +88 -7
- package/index.js +0 -1
|
@@ -0,0 +1,1289 @@
|
|
|
1
|
+
openapi: 3.0.3
|
|
2
|
+
info:
|
|
3
|
+
title: Soundlink Public API
|
|
4
|
+
version: 0.0.1-draft
|
|
5
|
+
description: |
|
|
6
|
+
Read-only campaign and metrics API for Soundlink partner organizations.
|
|
7
|
+
|
|
8
|
+
**Base URL:** `https://api.getsoundlink.com`
|
|
9
|
+
|
|
10
|
+
**Authentication:** `x-api-key` header using a `sk_*` API key issued by Soundlink Engineering.
|
|
11
|
+
```
|
|
12
|
+
x-api-key: sk_abc123_<token>
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
All responses are wrapped in a standard envelope:
|
|
16
|
+
```json
|
|
17
|
+
{ "data": <payload>, "meta": { "requestId": "<uuid>" } }
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Errors follow the same envelope shape with an `error` field instead of `data`.
|
|
21
|
+
|
|
22
|
+
servers:
|
|
23
|
+
- url: https://api.getsoundlink.com
|
|
24
|
+
description: Production
|
|
25
|
+
|
|
26
|
+
security:
|
|
27
|
+
- apiKeyAuth: []
|
|
28
|
+
|
|
29
|
+
tags:
|
|
30
|
+
- name: System
|
|
31
|
+
description: Connectivity and auth verification
|
|
32
|
+
- name: Campaigns
|
|
33
|
+
description: Campaign listing and detail
|
|
34
|
+
- name: Metrics
|
|
35
|
+
description: Campaign performance metrics
|
|
36
|
+
|
|
37
|
+
paths:
|
|
38
|
+
/v1/ping:
|
|
39
|
+
get:
|
|
40
|
+
operationId: ping
|
|
41
|
+
summary: Verify connectivity and authentication
|
|
42
|
+
description: |
|
|
43
|
+
Returns `{ "status": "ok" }` if the request is authenticated and the
|
|
44
|
+
API is reachable. Useful for verifying a newly issued key before making
|
|
45
|
+
data requests.
|
|
46
|
+
tags: [System]
|
|
47
|
+
security:
|
|
48
|
+
- apiKeyAuth: []
|
|
49
|
+
responses:
|
|
50
|
+
'200':
|
|
51
|
+
description: Authenticated and reachable
|
|
52
|
+
content:
|
|
53
|
+
application/json:
|
|
54
|
+
schema:
|
|
55
|
+
type: object
|
|
56
|
+
required: [data, meta]
|
|
57
|
+
properties:
|
|
58
|
+
data:
|
|
59
|
+
type: object
|
|
60
|
+
required: [status]
|
|
61
|
+
properties:
|
|
62
|
+
status:
|
|
63
|
+
type: string
|
|
64
|
+
example: ok
|
|
65
|
+
meta:
|
|
66
|
+
$ref: '#/components/schemas/Meta'
|
|
67
|
+
example:
|
|
68
|
+
data:
|
|
69
|
+
status: ok
|
|
70
|
+
meta:
|
|
71
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
72
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
73
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
74
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
75
|
+
|
|
76
|
+
/v1/campaigns:
|
|
77
|
+
get:
|
|
78
|
+
operationId: listCampaigns
|
|
79
|
+
summary: List campaigns
|
|
80
|
+
description: |
|
|
81
|
+
Returns all campaigns for the authenticated organization.
|
|
82
|
+
Intended for reporting and data warehouse sync.
|
|
83
|
+
tags: [Campaigns]
|
|
84
|
+
security:
|
|
85
|
+
- apiKeyAuth: []
|
|
86
|
+
parameters:
|
|
87
|
+
- $ref: '#/components/parameters/page'
|
|
88
|
+
- $ref: '#/components/parameters/pageSize100'
|
|
89
|
+
- name: sortBy
|
|
90
|
+
in: query
|
|
91
|
+
schema:
|
|
92
|
+
type: string
|
|
93
|
+
enum: [createdAt, status]
|
|
94
|
+
default: createdAt
|
|
95
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
96
|
+
responses:
|
|
97
|
+
'200':
|
|
98
|
+
description: Paginated list of campaigns
|
|
99
|
+
content:
|
|
100
|
+
application/json:
|
|
101
|
+
schema:
|
|
102
|
+
$ref: '#/components/schemas/CampaignListResponse'
|
|
103
|
+
example:
|
|
104
|
+
data:
|
|
105
|
+
items:
|
|
106
|
+
- campaignId: camp_abc123
|
|
107
|
+
organizationId: org_xyz
|
|
108
|
+
status: active
|
|
109
|
+
socialPlatform: meta
|
|
110
|
+
dailyBudget: 20.0
|
|
111
|
+
totalBudget: 140.0
|
|
112
|
+
campaignDuration: 7
|
|
113
|
+
createdAt: '2026-04-01T10:00:00Z'
|
|
114
|
+
updatedAt: '2026-04-08T12:00:00Z'
|
|
115
|
+
pagination:
|
|
116
|
+
page: 1
|
|
117
|
+
pageSize: 10
|
|
118
|
+
totalCount: 42
|
|
119
|
+
totalPages: 5
|
|
120
|
+
meta:
|
|
121
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
122
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
123
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
124
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
125
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
126
|
+
|
|
127
|
+
/v1/campaigns/{campaignId}:
|
|
128
|
+
get:
|
|
129
|
+
operationId: getCampaign
|
|
130
|
+
summary: Get campaign
|
|
131
|
+
description: Fetch full details for a single campaign.
|
|
132
|
+
tags: [Campaigns]
|
|
133
|
+
security:
|
|
134
|
+
- apiKeyAuth: []
|
|
135
|
+
parameters:
|
|
136
|
+
- $ref: '#/components/parameters/campaignId'
|
|
137
|
+
responses:
|
|
138
|
+
'200':
|
|
139
|
+
description: Campaign detail
|
|
140
|
+
content:
|
|
141
|
+
application/json:
|
|
142
|
+
schema:
|
|
143
|
+
$ref: '#/components/schemas/CampaignDetailResponse'
|
|
144
|
+
example:
|
|
145
|
+
data:
|
|
146
|
+
campaignId: camp_abc123
|
|
147
|
+
organizationId: org_xyz
|
|
148
|
+
status: active
|
|
149
|
+
socialPlatform: meta
|
|
150
|
+
dailyBudget: 20.0
|
|
151
|
+
totalBudget: 140.0
|
|
152
|
+
campaignDuration: 7
|
|
153
|
+
strategyType: custom
|
|
154
|
+
createdAt: '2026-04-01T10:00:00Z'
|
|
155
|
+
updatedAt: '2026-04-08T12:00:00Z'
|
|
156
|
+
meta:
|
|
157
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
158
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
159
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
160
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
161
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
162
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
163
|
+
|
|
164
|
+
/v1/campaigns/{campaignId}/metrics/overview:
|
|
165
|
+
get:
|
|
166
|
+
operationId: getCampaignMetricsOverview
|
|
167
|
+
summary: Campaign metrics overview
|
|
168
|
+
description: |
|
|
169
|
+
Campaign-level totals for a date range: spend, conversions, listeners,
|
|
170
|
+
streams, followers, and derived ratios. No per-day rows — use
|
|
171
|
+
`/metrics/breakdown` for those.
|
|
172
|
+
|
|
173
|
+
Suitable for dashboards and quick syncs.
|
|
174
|
+
tags: [Metrics]
|
|
175
|
+
security:
|
|
176
|
+
- apiKeyAuth: []
|
|
177
|
+
parameters:
|
|
178
|
+
- $ref: '#/components/parameters/campaignId'
|
|
179
|
+
- $ref: '#/components/parameters/startDate'
|
|
180
|
+
- $ref: '#/components/parameters/endDate'
|
|
181
|
+
responses:
|
|
182
|
+
'200':
|
|
183
|
+
description: Campaign totals
|
|
184
|
+
content:
|
|
185
|
+
application/json:
|
|
186
|
+
schema:
|
|
187
|
+
$ref: '#/components/schemas/MetricsOverviewResponse'
|
|
188
|
+
example:
|
|
189
|
+
data:
|
|
190
|
+
listeners: 4821
|
|
191
|
+
streams: 9340
|
|
192
|
+
followers: 312
|
|
193
|
+
impressions: 48210
|
|
194
|
+
ad_clicks: 1120
|
|
195
|
+
link_clicks: 890
|
|
196
|
+
spend_media: 134.50
|
|
197
|
+
spend_total: 168.13
|
|
198
|
+
fees: 33.63
|
|
199
|
+
currency: USD
|
|
200
|
+
cpl: 0.028
|
|
201
|
+
cpf: 0.43
|
|
202
|
+
streams_per_listener: 1.94
|
|
203
|
+
meta:
|
|
204
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
205
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
206
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
207
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
208
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
209
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
210
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
211
|
+
|
|
212
|
+
/v1/campaigns/{campaignId}/metrics/breakdown:
|
|
213
|
+
get:
|
|
214
|
+
operationId: getCampaignMetricsBreakdown
|
|
215
|
+
summary: Campaign metrics breakdown
|
|
216
|
+
description: |
|
|
217
|
+
Per-day metrics broken down by country. One row per
|
|
218
|
+
`(report_date, campaign_id, country_code)`. Can be large, so results
|
|
219
|
+
are paginated.
|
|
220
|
+
|
|
221
|
+
**Row schema:** `campaign_country_daily` v1.0 — the same schema used
|
|
222
|
+
in JSONL bulk exports. Rows are idempotent on the primary key
|
|
223
|
+
`(provider, account_id, report_date, campaign_id, country_code)`;
|
|
224
|
+
re-ingesting is safe.
|
|
225
|
+
|
|
226
|
+
**Mutability window:** rows for a given `report_date` can be revised
|
|
227
|
+
for up to 7 days after the date closes due to delayed events from
|
|
228
|
+
Meta and Spotify. Re-fetch or re-ingest accordingly.
|
|
229
|
+
|
|
230
|
+
Maps to the **Countries** tab in the Soundlink Insights UI.
|
|
231
|
+
Use for daily warehouse loads.
|
|
232
|
+
tags: [Metrics]
|
|
233
|
+
security:
|
|
234
|
+
- apiKeyAuth: []
|
|
235
|
+
parameters:
|
|
236
|
+
- $ref: '#/components/parameters/campaignId'
|
|
237
|
+
- $ref: '#/components/parameters/startDate'
|
|
238
|
+
- $ref: '#/components/parameters/endDate'
|
|
239
|
+
- $ref: '#/components/parameters/page'
|
|
240
|
+
- $ref: '#/components/parameters/pageSize500'
|
|
241
|
+
- name: sortBy
|
|
242
|
+
in: query
|
|
243
|
+
schema:
|
|
244
|
+
type: string
|
|
245
|
+
enum: [report_date, spend_total]
|
|
246
|
+
default: report_date
|
|
247
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
248
|
+
responses:
|
|
249
|
+
'200':
|
|
250
|
+
description: Paginated per-day country rows (`campaign_country_daily` schema)
|
|
251
|
+
content:
|
|
252
|
+
application/json:
|
|
253
|
+
schema:
|
|
254
|
+
$ref: '#/components/schemas/MetricsBreakdownResponse'
|
|
255
|
+
example:
|
|
256
|
+
data:
|
|
257
|
+
schemaVersion: '1.0'
|
|
258
|
+
items:
|
|
259
|
+
- provider: soundlink
|
|
260
|
+
account_id: a7ac3173-2f71-4e79-921f-d15d7112dd11
|
|
261
|
+
schema_version: '1.0'
|
|
262
|
+
report_date: '2026-04-01'
|
|
263
|
+
report_date_timezone: UTC
|
|
264
|
+
exported_at: '2026-05-20T03:00:00Z'
|
|
265
|
+
campaign_id: f1e28d31-c358-4284-9bef-00a2334625fd
|
|
266
|
+
campaign_name: Sleep Playlist
|
|
267
|
+
campaign_target_type: track
|
|
268
|
+
campaign_target_isrc: DEXW62500259
|
|
269
|
+
campaign_target_spotify_track_id: 6habFhsOp2NvndAvgiJ01P
|
|
270
|
+
campaign_target_playlist_id: null
|
|
271
|
+
country_code: US
|
|
272
|
+
impressions: 4821
|
|
273
|
+
ad_clicks: 112
|
|
274
|
+
link_clicks: 89
|
|
275
|
+
streams: 203
|
|
276
|
+
listeners: 145
|
|
277
|
+
followers: 12
|
|
278
|
+
streams_per_listener: 1.4
|
|
279
|
+
spend_media: 42.50
|
|
280
|
+
spend_total: 53.13
|
|
281
|
+
fees: 10.63
|
|
282
|
+
currency: USD
|
|
283
|
+
currency_account: USD
|
|
284
|
+
cpl: 0.293
|
|
285
|
+
cpf: 3.542
|
|
286
|
+
cpc_linkclick: 0.478
|
|
287
|
+
ctr_linkclick: 0.0185
|
|
288
|
+
ctr_adclick: 0.0232
|
|
289
|
+
cost_per_result: 3.542
|
|
290
|
+
result_type: follow
|
|
291
|
+
pagination:
|
|
292
|
+
page: 1
|
|
293
|
+
pageSize: 50
|
|
294
|
+
totalCount: 340
|
|
295
|
+
totalPages: 7
|
|
296
|
+
meta:
|
|
297
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
298
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
299
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
300
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
301
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
302
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
303
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
304
|
+
|
|
305
|
+
/v1/campaigns/{campaignId}/metrics/breakdown/export:
|
|
306
|
+
get:
|
|
307
|
+
operationId: exportCampaignMetricsBreakdown
|
|
308
|
+
summary: Campaign metrics breakdown export (JSONL)
|
|
309
|
+
description: |
|
|
310
|
+
Streams the full country-level metrics dataset for a campaign as
|
|
311
|
+
**newline-delimited JSON (JSONL)**. Every line is a complete, valid
|
|
312
|
+
JSON object conforming to the `campaign_country_daily` v1.0 schema
|
|
313
|
+
— identical to the rows returned by `GET /metrics/breakdown` but
|
|
314
|
+
without pagination or an envelope wrapper.
|
|
315
|
+
|
|
316
|
+
Designed for data pipeline consumers: load directly into BigQuery,
|
|
317
|
+
Snowflake, or any JSONL-aware ingest tool without cursor logic.
|
|
318
|
+
|
|
319
|
+
**Usage:**
|
|
320
|
+
```
|
|
321
|
+
GET /v1/campaigns/{campaignId}/metrics/breakdown/export
|
|
322
|
+
Accept: application/x-ndjson
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
**Date range:** defaults to the full campaign active period. Override
|
|
326
|
+
with `startDate` / `endDate`. **Responses are capped at 90 days** —
|
|
327
|
+
use `startDate` / `endDate` to slice through longer windows manually.
|
|
328
|
+
|
|
329
|
+
**Mutability:** rows for a given `report_date` can be revised for up
|
|
330
|
+
to 7 days after the date closes due to delayed events from Meta and
|
|
331
|
+
Spotify. Re-fetching and re-ingesting on the primary key is safe
|
|
332
|
+
(idempotent).
|
|
333
|
+
tags: [Metrics]
|
|
334
|
+
security:
|
|
335
|
+
- apiKeyAuth: []
|
|
336
|
+
parameters:
|
|
337
|
+
- $ref: '#/components/parameters/campaignId'
|
|
338
|
+
- $ref: '#/components/parameters/startDate'
|
|
339
|
+
- $ref: '#/components/parameters/endDate'
|
|
340
|
+
responses:
|
|
341
|
+
'200':
|
|
342
|
+
description: |
|
|
343
|
+
JSONL stream. Each line is a `campaign_country_daily` v1.0 row.
|
|
344
|
+
Lines are sorted by `(report_date asc, country_code)`.
|
|
345
|
+
headers:
|
|
346
|
+
Content-Disposition:
|
|
347
|
+
schema:
|
|
348
|
+
type: string
|
|
349
|
+
description: |
|
|
350
|
+
`attachment; filename="breakdown_{campaignId}_{startDate}_{endDate}.jsonl"`
|
|
351
|
+
example: 'attachment; filename="breakdown_f1e28d31_2026-04-01_2026-05-01.jsonl"'
|
|
352
|
+
X-Row-Count:
|
|
353
|
+
schema:
|
|
354
|
+
type: integer
|
|
355
|
+
description: Total number of rows in the response.
|
|
356
|
+
content:
|
|
357
|
+
application/x-ndjson:
|
|
358
|
+
schema:
|
|
359
|
+
$ref: '#/components/schemas/BreakdownRow'
|
|
360
|
+
example: |
|
|
361
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"6habFhsOp2NvndAvgiJ01P","campaign_target_playlist_id":null,"country_code":"US","impressions":4821,"ad_clicks":112,"link_clicks":89,"streams":203,"listeners":145,"followers":12,"streams_per_listener":1.4,"spend_media":42.50,"spend_total":53.13,"fees":10.63,"currency":"USD","currency_account":"USD","cpl":0.293,"cpf":3.542,"cpc_linkclick":0.478,"ctr_linkclick":0.0185,"ctr_adclick":0.0232,"cost_per_result":3.542,"result_type":"follow"}
|
|
362
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112dd11","schema_version":"1.0","report_date":"2026-04-01","report_date_timezone":"UTC","exported_at":"2026-05-20T03:00:00Z","campaign_id":"f1e28d31-c358-4284-9bef-00a2334625fd","campaign_name":"Sleep Playlist","campaign_target_type":"track","campaign_target_isrc":"DEXW62500259","campaign_target_spotify_track_id":"6habFhsOp2NvndAvgiJ01P","campaign_target_playlist_id":null,"country_code":"DE","impressions":2103,"ad_clicks":48,"link_clicks":31,"streams":87,"listeners":61,"followers":4,"streams_per_listener":1.43,"spend_media":18.20,"spend_total":22.75,"fees":4.55,"currency":"USD","currency_account":"USD","cpl":0.298,"cpf":4.55,"cpc_linkclick":0.587,"ctr_linkclick":0.0148,"ctr_adclick":0.0228,"cost_per_result":4.55,"result_type":"follow"}
|
|
363
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
364
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
365
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
366
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
367
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
368
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
369
|
+
|
|
370
|
+
/v1/campaigns/{campaignId}/metrics/engagement:
|
|
371
|
+
get:
|
|
372
|
+
operationId: getCampaignEngagement
|
|
373
|
+
summary: Campaign engagement breakdown
|
|
374
|
+
description: |
|
|
375
|
+
Per-day, per-track engagement metrics for a campaign. One row per
|
|
376
|
+
`(report_date, campaign_id, engagement_context, engaged_spotify_track_id)`.
|
|
377
|
+
|
|
378
|
+
**Key difference from `/metrics/breakdown`:** this endpoint covers the
|
|
379
|
+
full engagement window — including post-campaign streaming activity —
|
|
380
|
+
not just dates when the campaign was actively running. Use this for
|
|
381
|
+
catalog spillover analysis and long-tail retention.
|
|
382
|
+
|
|
383
|
+
**`engagement_context` values:**
|
|
384
|
+
- `catalog` — same-artist spillover (and direct promoted-track plays)
|
|
385
|
+
on track campaigns. `engaged_track_isrc` may equal
|
|
386
|
+
`campaign_target_isrc` (the promoted track itself) or differ
|
|
387
|
+
(spillover tracks).
|
|
388
|
+
- `playlist` — per-track performance inside the promoted playlist on
|
|
389
|
+
playlist campaigns. One row per track in the playlist per day.
|
|
390
|
+
|
|
391
|
+
**`listeners` is deduplicated within each row only.** Do not sum
|
|
392
|
+
`listeners` across days to get a campaign total — the same listener
|
|
393
|
+
can appear on multiple `report_date` rows.
|
|
394
|
+
|
|
395
|
+
Row schema: `campaign_engagement_daily` v1.0. Rows are idempotent on
|
|
396
|
+
the primary key; re-ingesting is safe.
|
|
397
|
+
|
|
398
|
+
**Mutability window:** rows for a given `report_date` can be revised
|
|
399
|
+
for up to 7 days after the date closes due to delayed Spotify
|
|
400
|
+
playback events.
|
|
401
|
+
tags: [Metrics]
|
|
402
|
+
security:
|
|
403
|
+
- apiKeyAuth: []
|
|
404
|
+
parameters:
|
|
405
|
+
- $ref: '#/components/parameters/campaignId'
|
|
406
|
+
- $ref: '#/components/parameters/startDate'
|
|
407
|
+
- $ref: '#/components/parameters/endDate'
|
|
408
|
+
- name: engagementContext
|
|
409
|
+
in: query
|
|
410
|
+
schema:
|
|
411
|
+
type: string
|
|
412
|
+
enum: [catalog, playlist]
|
|
413
|
+
description: |
|
|
414
|
+
Filter to a single engagement context. Omit to return both.
|
|
415
|
+
- $ref: '#/components/parameters/page'
|
|
416
|
+
- $ref: '#/components/parameters/pageSize500'
|
|
417
|
+
- name: sortBy
|
|
418
|
+
in: query
|
|
419
|
+
schema:
|
|
420
|
+
type: string
|
|
421
|
+
enum: [report_date, streams, listeners]
|
|
422
|
+
default: report_date
|
|
423
|
+
- $ref: '#/components/parameters/sortOrder'
|
|
424
|
+
responses:
|
|
425
|
+
'200':
|
|
426
|
+
description: Paginated per-day per-track engagement rows (`campaign_engagement_daily` schema)
|
|
427
|
+
content:
|
|
428
|
+
application/json:
|
|
429
|
+
schema:
|
|
430
|
+
$ref: '#/components/schemas/EngagementBreakdownResponse'
|
|
431
|
+
example:
|
|
432
|
+
data:
|
|
433
|
+
schemaVersion: '1.0'
|
|
434
|
+
items:
|
|
435
|
+
- provider: soundlink
|
|
436
|
+
account_id: a7ac3173-2f71-4e79-921f-d15d7112cc9a
|
|
437
|
+
schema_version: '1.0'
|
|
438
|
+
report_date: '2026-04-08'
|
|
439
|
+
report_date_timezone: UTC
|
|
440
|
+
exported_at: '2026-05-22T10:12:11Z'
|
|
441
|
+
campaign_id: 8ccd7b88-2591-4b94-848f-f142f5c6bba1
|
|
442
|
+
campaign_name: 9 To 5
|
|
443
|
+
campaign_target_type: track
|
|
444
|
+
campaign_target_isrc: DEXW62500272
|
|
445
|
+
campaign_target_spotify_track_id: 2RkZ5WPkKyBf0u8vN3dNgb
|
|
446
|
+
campaign_target_playlist_id: null
|
|
447
|
+
status: ended
|
|
448
|
+
engagement_context: catalog
|
|
449
|
+
country_code: US
|
|
450
|
+
engaged_track_isrc: DEXW62500001
|
|
451
|
+
engaged_spotify_track_id: 4cOdK2wGLETKBW3PvgPWqT
|
|
452
|
+
engaged_track_name: Till The Sunrise
|
|
453
|
+
playlist_position: null
|
|
454
|
+
new_listeners: 42
|
|
455
|
+
returning_listeners: 18
|
|
456
|
+
listeners: 60
|
|
457
|
+
new_listener_streams: 58
|
|
458
|
+
returning_listener_streams: 31
|
|
459
|
+
streams: 89
|
|
460
|
+
spl: 1.48
|
|
461
|
+
pagination:
|
|
462
|
+
page: 1
|
|
463
|
+
pageSize: 50
|
|
464
|
+
totalCount: 210
|
|
465
|
+
totalPages: 5
|
|
466
|
+
meta:
|
|
467
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
468
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
469
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
470
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
471
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
472
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
473
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
474
|
+
|
|
475
|
+
/v1/campaigns/{campaignId}/metrics/engagement/export:
|
|
476
|
+
get:
|
|
477
|
+
operationId: exportCampaignEngagement
|
|
478
|
+
summary: Campaign engagement export (JSONL)
|
|
479
|
+
description: |
|
|
480
|
+
Streams the full engagement dataset for a campaign as
|
|
481
|
+
**newline-delimited JSON (JSONL)**. Every line is a complete, valid
|
|
482
|
+
JSON object conforming to the `campaign_engagement_daily` v1.0 schema
|
|
483
|
+
— identical to the rows returned by `GET /metrics/engagement` but
|
|
484
|
+
without pagination or an envelope wrapper.
|
|
485
|
+
|
|
486
|
+
Designed for data pipeline consumers: load directly into BigQuery,
|
|
487
|
+
Snowflake, or any JSONL-aware ingest tool without cursor logic.
|
|
488
|
+
|
|
489
|
+
**Usage:**
|
|
490
|
+
```
|
|
491
|
+
GET /v1/campaigns/{campaignId}/metrics/engagement/export
|
|
492
|
+
Accept: application/x-ndjson
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
**Response body (one JSON object per line, no trailing comma):**
|
|
496
|
+
```
|
|
497
|
+
{"provider":"soundlink","report_date":"2026-04-01","streams":89,...}
|
|
498
|
+
{"provider":"soundlink","report_date":"2026-04-02","streams":104,...}
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
**Date range:** defaults to the full campaign lifetime plus 30 days
|
|
502
|
+
post-end to capture tail engagement. Override with `startDate` /
|
|
503
|
+
`endDate`. **Responses are capped at 90 days** — if the requested
|
|
504
|
+
range exceeds 90 days, the most recent 90 days are returned. Use
|
|
505
|
+
`startDate` / `endDate` to page through longer windows in 90-day
|
|
506
|
+
slices.
|
|
507
|
+
|
|
508
|
+
**Mutability:** same 7-day revision window as the paginated endpoint.
|
|
509
|
+
Re-fetching and re-ingesting on the primary key is safe (idempotent).
|
|
510
|
+
tags: [Metrics]
|
|
511
|
+
security:
|
|
512
|
+
- apiKeyAuth: []
|
|
513
|
+
parameters:
|
|
514
|
+
- $ref: '#/components/parameters/campaignId'
|
|
515
|
+
- $ref: '#/components/parameters/startDate'
|
|
516
|
+
- $ref: '#/components/parameters/endDate'
|
|
517
|
+
- name: engagementContext
|
|
518
|
+
in: query
|
|
519
|
+
schema:
|
|
520
|
+
type: string
|
|
521
|
+
enum: [catalog, playlist]
|
|
522
|
+
description: Filter to a single engagement context. Omit to return both.
|
|
523
|
+
responses:
|
|
524
|
+
'200':
|
|
525
|
+
description: |
|
|
526
|
+
JSONL stream. Each line is a `campaign_engagement_daily` v1.0 row.
|
|
527
|
+
Lines are sorted by `(report_date asc, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
528
|
+
headers:
|
|
529
|
+
Content-Disposition:
|
|
530
|
+
schema:
|
|
531
|
+
type: string
|
|
532
|
+
description: |
|
|
533
|
+
`attachment; filename="engagement_{campaignId}_{startDate}_{endDate}.jsonl"`
|
|
534
|
+
example: 'attachment; filename="engagement_8ccd7b88_2026-04-01_2026-05-01.jsonl"'
|
|
535
|
+
X-Row-Count:
|
|
536
|
+
schema:
|
|
537
|
+
type: integer
|
|
538
|
+
description: Total number of rows in the response. Useful for progress tracking when streaming.
|
|
539
|
+
content:
|
|
540
|
+
application/x-ndjson:
|
|
541
|
+
schema:
|
|
542
|
+
$ref: '#/components/schemas/EngagementRow'
|
|
543
|
+
example: |
|
|
544
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112cc9a","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"8ccd7b88-2591-4b94-848f-f142f5c6bba1","campaign_name":"9 To 5","campaign_target_type":"track","campaign_target_isrc":"DEXW62500272","campaign_target_spotify_track_id":"2RkZ5WPkKyBf0u8vN3dNgb","campaign_target_playlist_id":null,"status":"ended","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}
|
|
545
|
+
{"provider":"soundlink","account_id":"a7ac3173-2f71-4e79-921f-d15d7112cc9a","schema_version":"1.0","report_date":"2026-04-08","report_date_timezone":"UTC","exported_at":"2026-05-22T10:12:11Z","campaign_id":"8ccd7b88-2591-4b94-848f-f142f5c6bba1","campaign_name":"9 To 5","campaign_target_type":"track","campaign_target_isrc":"DEXW62500272","campaign_target_spotify_track_id":"2RkZ5WPkKyBf0u8vN3dNgb","campaign_target_playlist_id":null,"status":"ended","engagement_context":"catalog","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}
|
|
546
|
+
'400': { $ref: '#/components/responses/BadRequest' }
|
|
547
|
+
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
548
|
+
'403': { $ref: '#/components/responses/Forbidden' }
|
|
549
|
+
'404': { $ref: '#/components/responses/NotFound' }
|
|
550
|
+
'429': { $ref: '#/components/responses/RateLimited' }
|
|
551
|
+
'500': { $ref: '#/components/responses/InternalError' }
|
|
552
|
+
|
|
553
|
+
components:
|
|
554
|
+
securitySchemes:
|
|
555
|
+
apiKeyAuth:
|
|
556
|
+
type: apiKey
|
|
557
|
+
in: header
|
|
558
|
+
name: x-api-key
|
|
559
|
+
description: |
|
|
560
|
+
Pass your Soundlink `sk_*` API key in the `x-api-key` header.
|
|
561
|
+
Keys can carry explicit scopes (for example `campaigns:read`, `metrics:read`) enforced by the backend.
|
|
562
|
+
|
|
563
|
+
parameters:
|
|
564
|
+
campaignId:
|
|
565
|
+
name: campaignId
|
|
566
|
+
in: path
|
|
567
|
+
required: true
|
|
568
|
+
schema:
|
|
569
|
+
type: string
|
|
570
|
+
description: Campaign identifier (e.g. `camp_abc123`)
|
|
571
|
+
|
|
572
|
+
page:
|
|
573
|
+
name: page
|
|
574
|
+
in: query
|
|
575
|
+
schema:
|
|
576
|
+
type: integer
|
|
577
|
+
minimum: 1
|
|
578
|
+
default: 1
|
|
579
|
+
description: Page number (1-indexed)
|
|
580
|
+
|
|
581
|
+
pageSize100:
|
|
582
|
+
name: pageSize
|
|
583
|
+
in: query
|
|
584
|
+
schema:
|
|
585
|
+
type: integer
|
|
586
|
+
minimum: 1
|
|
587
|
+
maximum: 100
|
|
588
|
+
default: 10
|
|
589
|
+
description: Items per page (max 100)
|
|
590
|
+
|
|
591
|
+
pageSize500:
|
|
592
|
+
name: pageSize
|
|
593
|
+
in: query
|
|
594
|
+
schema:
|
|
595
|
+
type: integer
|
|
596
|
+
minimum: 1
|
|
597
|
+
maximum: 500
|
|
598
|
+
default: 50
|
|
599
|
+
description: Rows per page (max 500; higher default than list endpoints)
|
|
600
|
+
|
|
601
|
+
sortOrder:
|
|
602
|
+
name: sortOrder
|
|
603
|
+
in: query
|
|
604
|
+
schema:
|
|
605
|
+
type: string
|
|
606
|
+
enum: [asc, desc]
|
|
607
|
+
default: desc
|
|
608
|
+
description: Sort direction
|
|
609
|
+
|
|
610
|
+
startDate:
|
|
611
|
+
name: startDate
|
|
612
|
+
in: query
|
|
613
|
+
schema:
|
|
614
|
+
type: string
|
|
615
|
+
format: date
|
|
616
|
+
description: Inclusive start date (`YYYY-MM-DD`). Defaults to campaign start date.
|
|
617
|
+
|
|
618
|
+
endDate:
|
|
619
|
+
name: endDate
|
|
620
|
+
in: query
|
|
621
|
+
schema:
|
|
622
|
+
type: string
|
|
623
|
+
format: date
|
|
624
|
+
description: Inclusive end date (`YYYY-MM-DD`). Defaults to today.
|
|
625
|
+
|
|
626
|
+
schemas:
|
|
627
|
+
# --- Shared ---
|
|
628
|
+
|
|
629
|
+
Meta:
|
|
630
|
+
type: object
|
|
631
|
+
required: [requestId]
|
|
632
|
+
properties:
|
|
633
|
+
requestId:
|
|
634
|
+
type: string
|
|
635
|
+
format: uuid
|
|
636
|
+
description: Server-generated request ID. Include when contacting support.
|
|
637
|
+
|
|
638
|
+
Pagination:
|
|
639
|
+
type: object
|
|
640
|
+
required: [page, pageSize, totalCount, totalPages]
|
|
641
|
+
properties:
|
|
642
|
+
page:
|
|
643
|
+
type: integer
|
|
644
|
+
pageSize:
|
|
645
|
+
type: integer
|
|
646
|
+
totalCount:
|
|
647
|
+
type: integer
|
|
648
|
+
totalPages:
|
|
649
|
+
type: integer
|
|
650
|
+
|
|
651
|
+
Error:
|
|
652
|
+
type: object
|
|
653
|
+
required: [code, message]
|
|
654
|
+
properties:
|
|
655
|
+
code:
|
|
656
|
+
type: string
|
|
657
|
+
description: Stable snake_case error code.
|
|
658
|
+
enum:
|
|
659
|
+
- invalid_api_key
|
|
660
|
+
- api_key_revoked
|
|
661
|
+
- api_key_expired
|
|
662
|
+
- mixed_credentials
|
|
663
|
+
- insufficient_scope
|
|
664
|
+
- not_found
|
|
665
|
+
- campaign_not_found
|
|
666
|
+
- invalid_query_parameter
|
|
667
|
+
- invalid_date_range
|
|
668
|
+
- page_size_exceeded
|
|
669
|
+
- rate_limit_exceeded
|
|
670
|
+
- internal_error
|
|
671
|
+
message:
|
|
672
|
+
type: string
|
|
673
|
+
description: Human-readable error description. Do not parse programmatically.
|
|
674
|
+
|
|
675
|
+
ErrorResponse:
|
|
676
|
+
type: object
|
|
677
|
+
required: [error, meta]
|
|
678
|
+
properties:
|
|
679
|
+
error:
|
|
680
|
+
$ref: '#/components/schemas/Error'
|
|
681
|
+
meta:
|
|
682
|
+
$ref: '#/components/schemas/Meta'
|
|
683
|
+
|
|
684
|
+
# --- Campaign ---
|
|
685
|
+
|
|
686
|
+
CampaignStatus:
|
|
687
|
+
type: string
|
|
688
|
+
enum: [creating, active, paused, completed, failed]
|
|
689
|
+
|
|
690
|
+
CampaignSummary:
|
|
691
|
+
type: object
|
|
692
|
+
required:
|
|
693
|
+
[
|
|
694
|
+
campaignId,
|
|
695
|
+
organizationId,
|
|
696
|
+
status,
|
|
697
|
+
socialPlatform,
|
|
698
|
+
dailyBudget,
|
|
699
|
+
totalBudget,
|
|
700
|
+
campaignDuration,
|
|
701
|
+
createdAt,
|
|
702
|
+
updatedAt,
|
|
703
|
+
]
|
|
704
|
+
properties:
|
|
705
|
+
campaignId:
|
|
706
|
+
type: string
|
|
707
|
+
organizationId:
|
|
708
|
+
type: string
|
|
709
|
+
status:
|
|
710
|
+
$ref: '#/components/schemas/CampaignStatus'
|
|
711
|
+
socialPlatform:
|
|
712
|
+
type: string
|
|
713
|
+
enum: [meta]
|
|
714
|
+
dailyBudget:
|
|
715
|
+
type: number
|
|
716
|
+
description: USD
|
|
717
|
+
totalBudget:
|
|
718
|
+
type: number
|
|
719
|
+
description: USD
|
|
720
|
+
campaignDuration:
|
|
721
|
+
type: integer
|
|
722
|
+
description: Duration in days
|
|
723
|
+
createdAt:
|
|
724
|
+
type: string
|
|
725
|
+
format: date-time
|
|
726
|
+
updatedAt:
|
|
727
|
+
type: string
|
|
728
|
+
format: date-time
|
|
729
|
+
|
|
730
|
+
CampaignDetail:
|
|
731
|
+
allOf:
|
|
732
|
+
- $ref: '#/components/schemas/CampaignSummary'
|
|
733
|
+
- type: object
|
|
734
|
+
properties:
|
|
735
|
+
strategyType:
|
|
736
|
+
type: string
|
|
737
|
+
description: |
|
|
738
|
+
Growth strategy (e.g. `custom`, `maximum_growth`, `market_discovery`).
|
|
739
|
+
Set at campaign creation.
|
|
740
|
+
|
|
741
|
+
CampaignListResponse:
|
|
742
|
+
type: object
|
|
743
|
+
required: [data, meta]
|
|
744
|
+
properties:
|
|
745
|
+
data:
|
|
746
|
+
type: object
|
|
747
|
+
required: [items, pagination]
|
|
748
|
+
properties:
|
|
749
|
+
items:
|
|
750
|
+
type: array
|
|
751
|
+
items:
|
|
752
|
+
$ref: '#/components/schemas/CampaignSummary'
|
|
753
|
+
pagination:
|
|
754
|
+
$ref: '#/components/schemas/Pagination'
|
|
755
|
+
meta:
|
|
756
|
+
$ref: '#/components/schemas/Meta'
|
|
757
|
+
|
|
758
|
+
CampaignDetailResponse:
|
|
759
|
+
type: object
|
|
760
|
+
required: [data, meta]
|
|
761
|
+
properties:
|
|
762
|
+
data:
|
|
763
|
+
$ref: '#/components/schemas/CampaignDetail'
|
|
764
|
+
meta:
|
|
765
|
+
$ref: '#/components/schemas/Meta'
|
|
766
|
+
|
|
767
|
+
# --- Metrics ---
|
|
768
|
+
|
|
769
|
+
MetricsOverview:
|
|
770
|
+
type: object
|
|
771
|
+
description: |
|
|
772
|
+
Campaign-level totals aggregated across all countries for the requested
|
|
773
|
+
date range. Field names align with the `campaign_country_daily` row
|
|
774
|
+
schema — values here are the sum of country rows.
|
|
775
|
+
required:
|
|
776
|
+
[
|
|
777
|
+
listeners,
|
|
778
|
+
streams,
|
|
779
|
+
followers,
|
|
780
|
+
spend_media,
|
|
781
|
+
spend_total,
|
|
782
|
+
fees,
|
|
783
|
+
currency,
|
|
784
|
+
cpl,
|
|
785
|
+
cpf,
|
|
786
|
+
streams_per_listener,
|
|
787
|
+
]
|
|
788
|
+
properties:
|
|
789
|
+
listeners:
|
|
790
|
+
type: integer
|
|
791
|
+
description: Unique attributed Spotify listeners (sum of country rows).
|
|
792
|
+
streams:
|
|
793
|
+
type: integer
|
|
794
|
+
description: Attributed Spotify streams (sum of country rows).
|
|
795
|
+
followers:
|
|
796
|
+
type: integer
|
|
797
|
+
description: Attributed artist follower gains (sum of country rows).
|
|
798
|
+
impressions:
|
|
799
|
+
type: integer
|
|
800
|
+
nullable: true
|
|
801
|
+
description: Total Meta ad impressions. Null if not available.
|
|
802
|
+
ad_clicks:
|
|
803
|
+
type: integer
|
|
804
|
+
nullable: true
|
|
805
|
+
description: Total Meta ad clicks (all click types).
|
|
806
|
+
link_clicks:
|
|
807
|
+
type: integer
|
|
808
|
+
nullable: true
|
|
809
|
+
description: Outbound clicks to Spotify via the Soundlink landing page.
|
|
810
|
+
spend_media:
|
|
811
|
+
type: number
|
|
812
|
+
description: Amount billed to Meta for ad delivery. Excludes Soundlink fees. USD.
|
|
813
|
+
spend_total:
|
|
814
|
+
type: number
|
|
815
|
+
description: Total billed by Soundlink (spend_media + fees). USD.
|
|
816
|
+
fees:
|
|
817
|
+
type: number
|
|
818
|
+
description: Soundlink service fee (spend_total - spend_media). USD.
|
|
819
|
+
currency:
|
|
820
|
+
type: string
|
|
821
|
+
description: Currency for spend fields. Currently always `USD`.
|
|
822
|
+
cpl:
|
|
823
|
+
type: number
|
|
824
|
+
description: Cost per listener (spend_media / listeners).
|
|
825
|
+
cpf:
|
|
826
|
+
type: number
|
|
827
|
+
description: Cost per follower (spend_media / followers).
|
|
828
|
+
streams_per_listener:
|
|
829
|
+
type: number
|
|
830
|
+
description: streams / listeners. Zero if listeners is zero.
|
|
831
|
+
|
|
832
|
+
MetricsOverviewResponse:
|
|
833
|
+
type: object
|
|
834
|
+
required: [data, meta]
|
|
835
|
+
properties:
|
|
836
|
+
data:
|
|
837
|
+
$ref: '#/components/schemas/MetricsOverview'
|
|
838
|
+
meta:
|
|
839
|
+
$ref: '#/components/schemas/Meta'
|
|
840
|
+
|
|
841
|
+
BreakdownRow:
|
|
842
|
+
type: object
|
|
843
|
+
description: |
|
|
844
|
+
One row of the `campaign_country_daily` v1.0 schema.
|
|
845
|
+
Primary key: `(provider, account_id, report_date, campaign_id, country_code)`.
|
|
846
|
+
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
847
|
+
Values for a given `report_date` may be revised for up to 7 days after
|
|
848
|
+
the date closes due to delayed events from Meta and Spotify.
|
|
849
|
+
required:
|
|
850
|
+
- provider
|
|
851
|
+
- account_id
|
|
852
|
+
- schema_version
|
|
853
|
+
- report_date
|
|
854
|
+
- report_date_timezone
|
|
855
|
+
- exported_at
|
|
856
|
+
- campaign_id
|
|
857
|
+
- campaign_name
|
|
858
|
+
- campaign_target_type
|
|
859
|
+
- country_code
|
|
860
|
+
- streams
|
|
861
|
+
- listeners
|
|
862
|
+
- followers
|
|
863
|
+
- streams_per_listener
|
|
864
|
+
- spend_media
|
|
865
|
+
- spend_total
|
|
866
|
+
- fees
|
|
867
|
+
- currency
|
|
868
|
+
- currency_account
|
|
869
|
+
- cpl
|
|
870
|
+
- cpf
|
|
871
|
+
- cost_per_result
|
|
872
|
+
properties:
|
|
873
|
+
provider:
|
|
874
|
+
type: string
|
|
875
|
+
enum: [soundlink]
|
|
876
|
+
description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
|
|
877
|
+
account_id:
|
|
878
|
+
type: string
|
|
879
|
+
description: Soundlink organization ID (UUID).
|
|
880
|
+
schema_version:
|
|
881
|
+
type: string
|
|
882
|
+
description: Schema version. Pin your ingest pipeline to this value.
|
|
883
|
+
example: '1.0'
|
|
884
|
+
report_date:
|
|
885
|
+
type: string
|
|
886
|
+
format: date
|
|
887
|
+
description: UTC calendar date the metrics belong to (`YYYY-MM-DD`).
|
|
888
|
+
report_date_timezone:
|
|
889
|
+
type: string
|
|
890
|
+
enum: [UTC]
|
|
891
|
+
description: Always `UTC`.
|
|
892
|
+
exported_at:
|
|
893
|
+
type: string
|
|
894
|
+
format: date-time
|
|
895
|
+
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
896
|
+
campaign_id:
|
|
897
|
+
type: string
|
|
898
|
+
description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
|
|
899
|
+
campaign_name:
|
|
900
|
+
type: string
|
|
901
|
+
description: Human-readable campaign name.
|
|
902
|
+
campaign_target_type:
|
|
903
|
+
type: string
|
|
904
|
+
nullable: true
|
|
905
|
+
enum: [track, playlist]
|
|
906
|
+
description: Whether this campaign promotes a track or playlist. `null` if undetermined.
|
|
907
|
+
campaign_target_isrc:
|
|
908
|
+
type: string
|
|
909
|
+
nullable: true
|
|
910
|
+
description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
|
|
911
|
+
campaign_target_spotify_track_id:
|
|
912
|
+
type: string
|
|
913
|
+
nullable: true
|
|
914
|
+
description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
|
|
915
|
+
campaign_target_playlist_id:
|
|
916
|
+
type: string
|
|
917
|
+
nullable: true
|
|
918
|
+
description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
|
|
919
|
+
country_code:
|
|
920
|
+
type: string
|
|
921
|
+
description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
|
|
922
|
+
impressions:
|
|
923
|
+
type: integer
|
|
924
|
+
nullable: true
|
|
925
|
+
description: Total Meta ad impressions served in this country on this day.
|
|
926
|
+
ad_clicks:
|
|
927
|
+
type: integer
|
|
928
|
+
nullable: true
|
|
929
|
+
description: Total clicks on the Meta ad (all click types). Use `ctr_adclick` for ad-level CTR.
|
|
930
|
+
link_clicks:
|
|
931
|
+
type: integer
|
|
932
|
+
nullable: true
|
|
933
|
+
description: Clicks on "Continue with Spotify" on the Soundlink landing page. Use `cpc_linkclick` / `ctr_linkclick` for outbound CPC/CTR.
|
|
934
|
+
streams:
|
|
935
|
+
type: integer
|
|
936
|
+
description: Spotify streams attributed to this campaign in this country on this day (7-day click-through window). Observed events, not modelled estimates.
|
|
937
|
+
listeners:
|
|
938
|
+
type: integer
|
|
939
|
+
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.
|
|
940
|
+
followers:
|
|
941
|
+
type: integer
|
|
942
|
+
description: Spotify artist follower gains attributed to this campaign in this country on this day (7-day click-through window).
|
|
943
|
+
streams_per_listener:
|
|
944
|
+
type: number
|
|
945
|
+
description: streams / listeners for this row. Zero if listeners is zero.
|
|
946
|
+
spend_media:
|
|
947
|
+
type: number
|
|
948
|
+
description: Amount billed to Meta for ad delivery in this country on this day. Excludes Soundlink service fees. In `currency`.
|
|
949
|
+
spend_total:
|
|
950
|
+
type: number
|
|
951
|
+
description: Total billed by Soundlink (spend_media + fees). Computed as `spend_media / (1 - fee_pct)`.
|
|
952
|
+
fees:
|
|
953
|
+
type: number
|
|
954
|
+
description: Soundlink service fee (spend_total - spend_media).
|
|
955
|
+
currency:
|
|
956
|
+
type: string
|
|
957
|
+
description: Currency for spend fields. Currently always `USD`.
|
|
958
|
+
currency_account:
|
|
959
|
+
type: string
|
|
960
|
+
description: Account billing currency. Currently always `USD`. Will differ from `currency` once EUR delivery is available.
|
|
961
|
+
cpl:
|
|
962
|
+
type: number
|
|
963
|
+
description: Cost per listener (spend_media / listeners). Zero if listeners is zero.
|
|
964
|
+
cpf:
|
|
965
|
+
type: number
|
|
966
|
+
description: Cost per follower (spend_media / followers). Zero if followers is zero.
|
|
967
|
+
cpc_linkclick:
|
|
968
|
+
type: number
|
|
969
|
+
nullable: true
|
|
970
|
+
description: Cost per outbound click (spend_media / link_clicks). Null if link_clicks is null or zero.
|
|
971
|
+
ctr_linkclick:
|
|
972
|
+
type: number
|
|
973
|
+
nullable: true
|
|
974
|
+
description: Outbound CTR (link_clicks / impressions). Null if impressions is null or zero.
|
|
975
|
+
ctr_adclick:
|
|
976
|
+
type: number
|
|
977
|
+
nullable: true
|
|
978
|
+
description: Meta ad CTR (ad_clicks / impressions). Null if impressions is null or zero.
|
|
979
|
+
cost_per_result:
|
|
980
|
+
type: number
|
|
981
|
+
description: Cost per primary campaign result. Currently equivalent to `cpf` (cost per follower). See `result_type`.
|
|
982
|
+
result_type:
|
|
983
|
+
type: string
|
|
984
|
+
nullable: true
|
|
985
|
+
enum: [lp_click, stream, follow]
|
|
986
|
+
description: The conversion event used for `cost_per_result`. Currently always `follow`.
|
|
987
|
+
|
|
988
|
+
MetricsBreakdownResponse:
|
|
989
|
+
type: object
|
|
990
|
+
required: [data, meta]
|
|
991
|
+
properties:
|
|
992
|
+
data:
|
|
993
|
+
type: object
|
|
994
|
+
required: [schemaVersion, items, pagination]
|
|
995
|
+
properties:
|
|
996
|
+
schemaVersion:
|
|
997
|
+
type: string
|
|
998
|
+
description: Version of the `campaign_country_daily` row schema. Pin your ingest pipeline to this.
|
|
999
|
+
example: '1.0'
|
|
1000
|
+
items:
|
|
1001
|
+
type: array
|
|
1002
|
+
items:
|
|
1003
|
+
$ref: '#/components/schemas/BreakdownRow'
|
|
1004
|
+
pagination:
|
|
1005
|
+
$ref: '#/components/schemas/Pagination'
|
|
1006
|
+
meta:
|
|
1007
|
+
$ref: '#/components/schemas/Meta'
|
|
1008
|
+
|
|
1009
|
+
# --- Engagement ---
|
|
1010
|
+
|
|
1011
|
+
EngagementRow:
|
|
1012
|
+
type: object
|
|
1013
|
+
description: |
|
|
1014
|
+
One row of the `campaign_engagement_daily` v1.0 schema.
|
|
1015
|
+
Primary key: `(provider, account_id, report_date, campaign_id, engagement_context, country_code, engaged_spotify_track_id)`.
|
|
1016
|
+
Rows are idempotent — re-ingesting on the primary key is safe.
|
|
1017
|
+
Values for a given `report_date` may be revised for up to 7 days after
|
|
1018
|
+
the date closes due to delayed Spotify playback events.
|
|
1019
|
+
required:
|
|
1020
|
+
- provider
|
|
1021
|
+
- account_id
|
|
1022
|
+
- schema_version
|
|
1023
|
+
- report_date
|
|
1024
|
+
- report_date_timezone
|
|
1025
|
+
- exported_at
|
|
1026
|
+
- campaign_id
|
|
1027
|
+
- campaign_name
|
|
1028
|
+
- campaign_target_type
|
|
1029
|
+
- status
|
|
1030
|
+
- engagement_context
|
|
1031
|
+
- country_code
|
|
1032
|
+
- engaged_spotify_track_id
|
|
1033
|
+
- engaged_track_name
|
|
1034
|
+
- new_listeners
|
|
1035
|
+
- returning_listeners
|
|
1036
|
+
- listeners
|
|
1037
|
+
- new_listener_streams
|
|
1038
|
+
- returning_listener_streams
|
|
1039
|
+
- streams
|
|
1040
|
+
- spl
|
|
1041
|
+
properties:
|
|
1042
|
+
provider:
|
|
1043
|
+
type: string
|
|
1044
|
+
enum: [soundlink]
|
|
1045
|
+
description: Always `soundlink`. Identifies the data provider for multi-source warehouses.
|
|
1046
|
+
account_id:
|
|
1047
|
+
type: string
|
|
1048
|
+
description: Soundlink organization ID (UUID).
|
|
1049
|
+
schema_version:
|
|
1050
|
+
type: string
|
|
1051
|
+
description: Schema version string. Pin your ingest pipeline to this value.
|
|
1052
|
+
example: '1.0'
|
|
1053
|
+
report_date:
|
|
1054
|
+
type: string
|
|
1055
|
+
format: date
|
|
1056
|
+
description: UTC calendar date the metrics belong to (`YYYY-MM-DD`). Rows can change for up to 7 days after close.
|
|
1057
|
+
report_date_timezone:
|
|
1058
|
+
type: string
|
|
1059
|
+
enum: [UTC]
|
|
1060
|
+
description: Always `UTC`.
|
|
1061
|
+
exported_at:
|
|
1062
|
+
type: string
|
|
1063
|
+
format: date-time
|
|
1064
|
+
description: ISO 8601 UTC timestamp when this row was generated. Use for deduplication if the same `report_date` is re-delivered.
|
|
1065
|
+
campaign_id:
|
|
1066
|
+
type: string
|
|
1067
|
+
description: Soundlink campaign UUID. Stable for the lifetime of the campaign.
|
|
1068
|
+
campaign_name:
|
|
1069
|
+
type: string
|
|
1070
|
+
description: Human-readable campaign name.
|
|
1071
|
+
campaign_target_type:
|
|
1072
|
+
type: string
|
|
1073
|
+
nullable: true
|
|
1074
|
+
enum: [track, playlist]
|
|
1075
|
+
description: Whether this campaign promotes a track or a playlist. `null` if undetermined.
|
|
1076
|
+
campaign_target_isrc:
|
|
1077
|
+
type: string
|
|
1078
|
+
nullable: true
|
|
1079
|
+
description: ISRC of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
|
|
1080
|
+
campaign_target_spotify_track_id:
|
|
1081
|
+
type: string
|
|
1082
|
+
nullable: true
|
|
1083
|
+
description: Spotify track ID of the promoted track. Populated when `campaign_target_type = track`; otherwise `null`.
|
|
1084
|
+
campaign_target_playlist_id:
|
|
1085
|
+
type: string
|
|
1086
|
+
nullable: true
|
|
1087
|
+
description: Spotify playlist ID. Populated when `campaign_target_type = playlist`; otherwise `null`.
|
|
1088
|
+
status:
|
|
1089
|
+
type: string
|
|
1090
|
+
enum: [active, ended, scheduled]
|
|
1091
|
+
description: |
|
|
1092
|
+
Campaign lifecycle status on `report_date`.
|
|
1093
|
+
`active` = campaign was running; `ended` = campaign had ended or was refunded;
|
|
1094
|
+
`scheduled` = `report_date` is before campaign start.
|
|
1095
|
+
Post-campaign rows will have `status = ended`.
|
|
1096
|
+
engagement_context:
|
|
1097
|
+
type: string
|
|
1098
|
+
enum: [catalog, playlist]
|
|
1099
|
+
description: |
|
|
1100
|
+
Which dashboard section the row maps to.
|
|
1101
|
+
`catalog` = same-artist spillover (and direct promoted-track plays) on track campaigns.
|
|
1102
|
+
`playlist` = per-track performance inside the promoted playlist on playlist campaigns.
|
|
1103
|
+
country_code:
|
|
1104
|
+
type: string
|
|
1105
|
+
description: ISO 3166-1 alpha-2. Derived from the listener's IP at time of engagement. Uppercase.
|
|
1106
|
+
example: US
|
|
1107
|
+
engaged_track_isrc:
|
|
1108
|
+
type: string
|
|
1109
|
+
nullable: true
|
|
1110
|
+
description: |
|
|
1111
|
+
ISRC of the track that received listens. May differ from `campaign_target_isrc`
|
|
1112
|
+
for catalog spillover rows. `null` if ISRC could not be resolved.
|
|
1113
|
+
engaged_spotify_track_id:
|
|
1114
|
+
type: string
|
|
1115
|
+
description: |
|
|
1116
|
+
Stable track identifier used in the primary key. Currently this is the
|
|
1117
|
+
Spotify track ID for the engaged track.
|
|
1118
|
+
example: 4cOdK2wGLETKBW3PvgPWqT
|
|
1119
|
+
engaged_track_name:
|
|
1120
|
+
type: string
|
|
1121
|
+
description: Display name of the engaged track.
|
|
1122
|
+
playlist_position:
|
|
1123
|
+
type: integer
|
|
1124
|
+
nullable: true
|
|
1125
|
+
minimum: 1
|
|
1126
|
+
description: |
|
|
1127
|
+
1-based slot index of the engaged track in the promoted playlist on `report_date`.
|
|
1128
|
+
Populated for `engagement_context = playlist` when playlist snapshot data is available.
|
|
1129
|
+
`null` for catalog rows and until position data is delivered (reserved for future delivery in v1.0).
|
|
1130
|
+
new_listeners:
|
|
1131
|
+
type: integer
|
|
1132
|
+
minimum: 0
|
|
1133
|
+
description: Unique listeners whose first play of this track on this smart link occurred on `report_date`.
|
|
1134
|
+
returning_listeners:
|
|
1135
|
+
type: integer
|
|
1136
|
+
minimum: 0
|
|
1137
|
+
description: Unique listeners who played this track on `report_date` but whose first play was on an earlier date.
|
|
1138
|
+
listeners:
|
|
1139
|
+
type: integer
|
|
1140
|
+
minimum: 0
|
|
1141
|
+
description: |
|
|
1142
|
+
Total unique listeners on `report_date`: `new_listeners + returning_listeners`.
|
|
1143
|
+
**Do not sum across days** — the same listener can appear on multiple `report_date` rows.
|
|
1144
|
+
new_listener_streams:
|
|
1145
|
+
type: integer
|
|
1146
|
+
minimum: 0
|
|
1147
|
+
description: Stream count from new listeners on `report_date`.
|
|
1148
|
+
returning_listener_streams:
|
|
1149
|
+
type: integer
|
|
1150
|
+
minimum: 0
|
|
1151
|
+
description: Stream count from returning listeners on `report_date`.
|
|
1152
|
+
streams:
|
|
1153
|
+
type: integer
|
|
1154
|
+
minimum: 0
|
|
1155
|
+
description: |
|
|
1156
|
+
Total streams on `report_date`: `new_listener_streams + returning_listener_streams`.
|
|
1157
|
+
Safe to sum within a day; summing across days counts repeat listens.
|
|
1158
|
+
spl:
|
|
1159
|
+
type: number
|
|
1160
|
+
description: Streams per listener (`streams / listeners`). Zero if `listeners` is zero.
|
|
1161
|
+
|
|
1162
|
+
EngagementBreakdownResponse:
|
|
1163
|
+
type: object
|
|
1164
|
+
required: [data, meta]
|
|
1165
|
+
properties:
|
|
1166
|
+
data:
|
|
1167
|
+
type: object
|
|
1168
|
+
required: [schemaVersion, items, pagination]
|
|
1169
|
+
properties:
|
|
1170
|
+
schemaVersion:
|
|
1171
|
+
type: string
|
|
1172
|
+
description: Version of the `campaign_engagement_daily` row schema. Pin your ingest pipeline to this.
|
|
1173
|
+
example: '1.0'
|
|
1174
|
+
items:
|
|
1175
|
+
type: array
|
|
1176
|
+
items:
|
|
1177
|
+
$ref: '#/components/schemas/EngagementRow'
|
|
1178
|
+
pagination:
|
|
1179
|
+
$ref: '#/components/schemas/Pagination'
|
|
1180
|
+
meta:
|
|
1181
|
+
$ref: '#/components/schemas/Meta'
|
|
1182
|
+
|
|
1183
|
+
responses:
|
|
1184
|
+
BadRequest:
|
|
1185
|
+
description: Invalid query parameter or date range
|
|
1186
|
+
content:
|
|
1187
|
+
application/json:
|
|
1188
|
+
schema:
|
|
1189
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
1190
|
+
examples:
|
|
1191
|
+
invalid_query_parameter:
|
|
1192
|
+
value:
|
|
1193
|
+
error:
|
|
1194
|
+
code: invalid_query_parameter
|
|
1195
|
+
message: 'pageSize must be an integer between 1 and 500.'
|
|
1196
|
+
meta:
|
|
1197
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1198
|
+
invalid_date_range:
|
|
1199
|
+
value:
|
|
1200
|
+
error:
|
|
1201
|
+
code: invalid_date_range
|
|
1202
|
+
message: 'endDate must not be before startDate.'
|
|
1203
|
+
meta:
|
|
1204
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1205
|
+
|
|
1206
|
+
Unauthorized:
|
|
1207
|
+
description: Missing, malformed, revoked, or expired API key
|
|
1208
|
+
headers:
|
|
1209
|
+
Retry-After:
|
|
1210
|
+
schema:
|
|
1211
|
+
type: integer
|
|
1212
|
+
description: Present only on `rate_limit_exceeded`
|
|
1213
|
+
content:
|
|
1214
|
+
application/json:
|
|
1215
|
+
schema:
|
|
1216
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
1217
|
+
examples:
|
|
1218
|
+
invalid_api_key:
|
|
1219
|
+
value:
|
|
1220
|
+
error:
|
|
1221
|
+
code: invalid_api_key
|
|
1222
|
+
message: 'Authorization header is missing or malformed.'
|
|
1223
|
+
meta:
|
|
1224
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1225
|
+
api_key_revoked:
|
|
1226
|
+
value:
|
|
1227
|
+
error:
|
|
1228
|
+
code: api_key_revoked
|
|
1229
|
+
message: 'This API key has been revoked. Contact Soundlink Engineering to mint a new key.'
|
|
1230
|
+
meta:
|
|
1231
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1232
|
+
|
|
1233
|
+
Forbidden:
|
|
1234
|
+
description: Valid key but missing required scope
|
|
1235
|
+
content:
|
|
1236
|
+
application/json:
|
|
1237
|
+
schema:
|
|
1238
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
1239
|
+
example:
|
|
1240
|
+
error:
|
|
1241
|
+
code: insufficient_scope
|
|
1242
|
+
message: 'This key does not have the metrics:read scope.'
|
|
1243
|
+
meta:
|
|
1244
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1245
|
+
|
|
1246
|
+
NotFound:
|
|
1247
|
+
description: Campaign not found, belongs to another org, or feature flag is off
|
|
1248
|
+
content:
|
|
1249
|
+
application/json:
|
|
1250
|
+
schema:
|
|
1251
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
1252
|
+
example:
|
|
1253
|
+
error:
|
|
1254
|
+
code: campaign_not_found
|
|
1255
|
+
message: 'Campaign not found.'
|
|
1256
|
+
meta:
|
|
1257
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1258
|
+
|
|
1259
|
+
RateLimited:
|
|
1260
|
+
description: Per-key rate limit exceeded (60/min, 600/hr)
|
|
1261
|
+
headers:
|
|
1262
|
+
Retry-After:
|
|
1263
|
+
required: true
|
|
1264
|
+
schema:
|
|
1265
|
+
type: integer
|
|
1266
|
+
description: Seconds until the rate limit resets
|
|
1267
|
+
content:
|
|
1268
|
+
application/json:
|
|
1269
|
+
schema:
|
|
1270
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
1271
|
+
example:
|
|
1272
|
+
error:
|
|
1273
|
+
code: rate_limit_exceeded
|
|
1274
|
+
message: 'Rate limit exceeded. Retry after the number of seconds indicated in the Retry-After header.'
|
|
1275
|
+
meta:
|
|
1276
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|
|
1277
|
+
|
|
1278
|
+
InternalError:
|
|
1279
|
+
description: Unexpected server error
|
|
1280
|
+
content:
|
|
1281
|
+
application/json:
|
|
1282
|
+
schema:
|
|
1283
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
1284
|
+
example:
|
|
1285
|
+
error:
|
|
1286
|
+
code: internal_error
|
|
1287
|
+
message: 'An unexpected error occurred. Contact support with the requestId.'
|
|
1288
|
+
meta:
|
|
1289
|
+
requestId: 550e8400-e29b-41d4-a716-446655440000
|