soundlink 2.13.0 → 2.15.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.
@@ -1,7 +1,7 @@
1
1
  openapi: 3.0.3
2
2
  info:
3
3
  title: Soundlink Public API
4
- version: 0.0.1-draft
4
+ version: 1.0.0
5
5
  description: |
6
6
  Campaign listing, metrics, and write operations for Soundlink partner organizations.
7
7
 
@@ -326,11 +326,13 @@ paths:
326
326
  /v1/pixels/{pixelId}/test-events:
327
327
  post:
328
328
  operationId: sendPixelTestEvents
329
- summary: Send a test conversion event to a pixel
329
+ summary: Send test conversion events to a pixel
330
330
  description: |
331
- Sends a live Meta Conversions API event named `Soundlink Stream` to
332
- `pixelId` with its stored access token. This is not a sandbox event:
333
- it appears in the pixel's Events Manager as a regular event. This
331
+ Sends live Meta Conversions API events named `Soundlink Auth`,
332
+ `Soundlink Stream`, `Soundlink Stream Value` (value 0 USD),
333
+ `Soundlink Follower`, and `Soundlink Artist Follower` to `pixelId` in
334
+ one request with its stored access token. These are not sandbox
335
+ events: they appear in the pixel's Events Manager as regular events. This
334
336
  request has no body.
335
337
 
336
338
  Returns `404 not_found` when the pixel is not configured for the
@@ -998,17 +1000,66 @@ paths:
998
1000
  '429': { $ref: '#/components/responses/RateLimited' }
999
1001
  '500': { $ref: '#/components/responses/InternalError' }
1000
1002
 
1003
+ /v1/campaigns/activity/batch:
1004
+ post:
1005
+ operationId: batchCampaignActivity
1006
+ summary: Batch campaign activity
1007
+ description: |
1008
+ Same activity page as `GET /v1/campaigns/{campaignId}/activity`, for up
1009
+ to 50 campaign IDs in one request (counts as one rate-limit unit).
1010
+
1011
+ Shared `page`, `pageSize`, and `startDate` apply to every authorized
1012
+ campaign. Unauthorized or unknown IDs are omitted from `data.items`
1013
+ (not errors). Requires org feature flag `public_api_campaign_batch`
1014
+ (404 when off).
1015
+
1016
+ Requires the `campaigns:read` scope. Accepts API key or OAuth Bearer.
1017
+ tags: [Campaigns]
1018
+ x-required-scope: campaigns:read
1019
+ security:
1020
+ - apiKeyBearerAuth: []
1021
+ - oauthBearer: []
1022
+ requestBody:
1023
+ required: true
1024
+ content:
1025
+ application/json:
1026
+ schema:
1027
+ $ref: '#/components/schemas/CampaignActivityBatchRequest'
1028
+ example:
1029
+ campaignIds:
1030
+ - f1e28d31-c358-4284-9bef-00a2334625fd
1031
+ - a2b39e42-d469-5395-ac0f-11b3445736fe
1032
+ page: 1
1033
+ pageSize: 20
1034
+ startDate: '2026-03-01T00:00:00.000Z'
1035
+ responses:
1036
+ '200':
1037
+ description: Activity page per authorized campaign
1038
+ content:
1039
+ application/json:
1040
+ schema:
1041
+ $ref: '#/components/schemas/CampaignActivityBatchResponse'
1042
+ '400': { $ref: '#/components/responses/BadRequest' }
1043
+ '401': { $ref: '#/components/responses/Unauthorized' }
1044
+ '403': { $ref: '#/components/responses/Forbidden' }
1045
+ '404': { $ref: '#/components/responses/NotFound' }
1046
+ '429': { $ref: '#/components/responses/RateLimited' }
1047
+ '500': { $ref: '#/components/responses/InternalError' }
1048
+
1001
1049
  /v1/campaigns/{campaignId}/activity:
1002
1050
  get:
1003
1051
  operationId: getCampaignActivity
1004
1052
  summary: List campaign activity
1005
1053
  description: |
1006
- Returns a page of creative adds, budget changes, tier updates, country
1007
- updates, playlist redirect heals, and auto-renew changes for one campaign.
1054
+ Returns a page of creative adds, creative pause/resume (user request or
1055
+ Meta sync), budget changes, tier updates, country updates, playlist
1056
+ redirect heals, and auto-renew changes for one campaign.
1008
1057
 
1009
- Each item is an event type, a timestamp, and a short summary. The list
1010
- does not include campaign creation or pausing an old creative. Fee amounts,
1011
- Stripe ids, and internal file URIs are omitted.
1058
+ Each item is an event type, a timestamp, and a short summary. Replacing
1059
+ a creative appears as a pause of the old creative plus
1060
+ `CAMPAIGN_AD_CREATIVES_ADDED` for the new one. The list does not include
1061
+ campaign creation. Fee amounts, Stripe ids, and internal file URIs are
1062
+ omitted.
1012
1063
 
1013
1064
  `startDate` keeps events at or after that moment. A calendar date starts
1014
1065
  at 00:00:00Z. Omit it to page through the full history. Any waiting rule,
@@ -1054,6 +1105,9 @@ paths:
1054
1105
  example:
1055
1106
  data:
1056
1107
  items:
1108
+ - event_type: CAMPAIGN_CREATIVE_STATUS_UPDATE_REQUESTED
1109
+ timestamp: '2026-03-03T12:00:00.000Z'
1110
+ summary: Creative paused by user
1057
1111
  - event_type: CAMPAIGN_AD_CREATIVES_ADDED
1058
1112
  timestamp: '2026-03-02T15:04:05.000Z'
1059
1113
  summary: Creatives added (2)
@@ -1063,7 +1117,7 @@ paths:
1063
1117
  pagination:
1064
1118
  page: 1
1065
1119
  pageSize: 20
1066
- totalCount: 2
1120
+ totalCount: 3
1067
1121
  totalPages: 1
1068
1122
  meta:
1069
1123
  requestId: 550e8400-e29b-41d4-a716-446655440000
@@ -1074,6 +1128,49 @@ paths:
1074
1128
  '429': { $ref: '#/components/responses/RateLimited' }
1075
1129
  '500': { $ref: '#/components/responses/InternalError' }
1076
1130
 
1131
+ /v1/campaigns/metrics/overview/batch:
1132
+ post:
1133
+ operationId: batchCampaignMetricsOverview
1134
+ summary: Batch campaign metrics overview
1135
+ description: |
1136
+ Same totals as `GET /v1/campaigns/{campaignId}/metrics/overview`, for
1137
+ up to 50 campaign IDs in one request (counts as one rate-limit unit).
1138
+
1139
+ Unauthorized or unknown IDs are omitted from `data.items` (not errors).
1140
+ Requires org feature flag `public_api_campaign_batch` (404 when off).
1141
+
1142
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
1143
+ tags: [Metrics]
1144
+ security:
1145
+ - apiKeyBearerAuth: []
1146
+ - oauthBearer: []
1147
+ x-required-scope: metrics:read
1148
+ requestBody:
1149
+ required: true
1150
+ content:
1151
+ application/json:
1152
+ schema:
1153
+ $ref: '#/components/schemas/CampaignMetricsOverviewBatchRequest'
1154
+ example:
1155
+ campaignIds:
1156
+ - f1e28d31-c358-4284-9bef-00a2334625fd
1157
+ - a2b39e42-d469-5395-ac0f-11b3445736fe
1158
+ startDate: '2026-04-01'
1159
+ endDate: '2026-04-08'
1160
+ responses:
1161
+ '200':
1162
+ description: Overview totals per authorized campaign
1163
+ content:
1164
+ application/json:
1165
+ schema:
1166
+ $ref: '#/components/schemas/CampaignMetricsOverviewBatchResponse'
1167
+ '400': { $ref: '#/components/responses/BadRequest' }
1168
+ '401': { $ref: '#/components/responses/Unauthorized' }
1169
+ '403': { $ref: '#/components/responses/Forbidden' }
1170
+ '404': { $ref: '#/components/responses/NotFound' }
1171
+ '429': { $ref: '#/components/responses/RateLimited' }
1172
+ '500': { $ref: '#/components/responses/InternalError' }
1173
+
1077
1174
  /v1/campaigns/{campaignId}/metrics/overview:
1078
1175
  get:
1079
1176
  operationId: getCampaignMetricsOverview
@@ -1128,6 +1225,49 @@ paths:
1128
1225
  '429': { $ref: '#/components/responses/RateLimited' }
1129
1226
  '500': { $ref: '#/components/responses/InternalError' }
1130
1227
 
1228
+ /v1/campaigns/metrics/creatives/batch:
1229
+ post:
1230
+ operationId: batchCampaignCreativeMetrics
1231
+ summary: Batch campaign creative metrics
1232
+ description: |
1233
+ Same lifetime creative snapshot as
1234
+ `GET /v1/campaigns/{campaignId}/metrics/creatives`, for up to 50
1235
+ campaign IDs in one request (counts as one rate-limit unit).
1236
+
1237
+ Unauthorized or unknown IDs are omitted from `data.items` (not errors).
1238
+ Requires org feature flag `public_api_campaign_batch` (404 when off).
1239
+ `startDate` and `endDate` are rejected on the body.
1240
+
1241
+ Requires the `metrics:read` scope. Accepts API key or OAuth Bearer.
1242
+ tags: [Metrics]
1243
+ security:
1244
+ - apiKeyBearerAuth: []
1245
+ - oauthBearer: []
1246
+ x-required-scope: metrics:read
1247
+ requestBody:
1248
+ required: true
1249
+ content:
1250
+ application/json:
1251
+ schema:
1252
+ $ref: '#/components/schemas/CampaignMetricsCreativesBatchRequest'
1253
+ example:
1254
+ campaignIds:
1255
+ - f1e28d31-c358-4284-9bef-00a2334625fd
1256
+ - a2b39e42-d469-5395-ac0f-11b3445736fe
1257
+ responses:
1258
+ '200':
1259
+ description: Creative metrics per authorized campaign
1260
+ content:
1261
+ application/json:
1262
+ schema:
1263
+ $ref: '#/components/schemas/CampaignMetricsCreativesBatchResponse'
1264
+ '400': { $ref: '#/components/responses/BadRequest' }
1265
+ '401': { $ref: '#/components/responses/Unauthorized' }
1266
+ '403': { $ref: '#/components/responses/Forbidden' }
1267
+ '404': { $ref: '#/components/responses/NotFound' }
1268
+ '429': { $ref: '#/components/responses/RateLimited' }
1269
+ '500': { $ref: '#/components/responses/InternalError' }
1270
+
1131
1271
  /v1/campaigns/{campaignId}/metrics/creatives:
1132
1272
  get:
1133
1273
  operationId: getCampaignCreativeMetrics
@@ -1140,6 +1280,9 @@ paths:
1140
1280
  of the same track stay separate. This is a snapshot, not a date range.
1141
1281
  `startDate` and `endDate` are rejected.
1142
1282
 
1283
+ Children include `delivery_state` for partner-upload Meta disapproval
1284
+ (not on parent groups). See `CreativeMetricsChild`.
1285
+
1143
1286
  Spend is omitted until media spend and fees can be split. Ratios use
1144
1287
  the same lifetime basis as the Creatives tab.
1145
1288
 
@@ -1183,6 +1326,7 @@ paths:
1183
1326
  cpf: 1.5
1184
1327
  cpc_linkclick: 0.5
1185
1328
  frequency: 2
1329
+ delivery_state: null
1186
1330
  - caption: Daytime version
1187
1331
  language: en
1188
1332
  spotify_track_id: 11dFghVXANMlKmJXsNCbNl
@@ -1195,6 +1339,7 @@ paths:
1195
1339
  cpf: 1
1196
1340
  cpc_linkclick: 0.25
1197
1341
  frequency: 1.5
1342
+ delivery_state: null
1198
1343
  meta:
1199
1344
  requestId: 550e8400-e29b-41d4-a716-446655440000
1200
1345
  '400': { $ref: '#/components/responses/BadRequest' }
@@ -1650,10 +1795,9 @@ paths:
1650
1795
  that has first plays (dates with no first plays have no row), where the
1651
1796
  cohort date is the UTC date listeners first played via the campaign soundlink.
1652
1797
  A listener's cohort date is their earliest first play across all countries.
1653
- Conforms to the `soundlink_cohort_retention_daily` v1.0 schema (same row
1798
+ Conforms to the `soundlink_cohort_retention_daily` v1.1 schema (same row
1654
1799
  shape as `GET /v1/soundlinks/{soundlinkId}/metrics/retention`). All rows
1655
- are returned in `data.items` (one per cohort date), so there is no
1656
- pagination.
1800
+ are returned in `data.items`, so there is no pagination.
1657
1801
 
1658
1802
  The campaign's `smart_link_id` is resolved from `dim_campaigns_current`
1659
1803
  before the retention query runs.
@@ -1664,8 +1808,13 @@ paths:
1664
1808
  - `retention_by_day_N`: share of the cohort (`cohort_size`) who played again on any
1665
1809
  day from 1 to N (end-day, cumulative). Each listener is counted once, so the
1666
1810
  by-day rate never decreases within a row.
1811
+ - `streams_on_day_N`: attributed plays on exactly day N after first play.
1667
1812
  - A day-N value is `null` until day N has passed for that cohort date.
1668
1813
 
1814
+ Omit `groupBy` for the global rollup (`country_code` is `null`; counts are summed
1815
+ over acquisition countries and rates are recomputed). `groupBy=country` returns one
1816
+ item per cohort date and acquisition country (`XX` when unknown).
1817
+
1669
1818
  **Known limitation:** end-day rates are cumulative per listener, so whether
1670
1819
  day-3 returners also returned on day 2 is not recoverable from the end-day
1671
1820
  columns. Use the exact-day `returned_on_day_N` columns for day-by-day behaviour.
@@ -1693,9 +1842,15 @@ paths:
1693
1842
  - $ref: '#/components/parameters/campaignId'
1694
1843
  - $ref: '#/components/parameters/startDate'
1695
1844
  - $ref: '#/components/parameters/endDate'
1845
+ - name: groupBy
1846
+ in: query
1847
+ required: false
1848
+ schema:
1849
+ type: string
1850
+ enum: [country]
1696
1851
  responses:
1697
1852
  '200':
1698
- description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` ascending.
1853
+ description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` (then `country_code` when grouped).
1699
1854
  content:
1700
1855
  application/json:
1701
1856
  schema:
@@ -1707,6 +1862,65 @@ paths:
1707
1862
  '429': { $ref: '#/components/responses/RateLimited' }
1708
1863
  '500': { $ref: '#/components/responses/InternalError' }
1709
1864
 
1865
+ /v1/campaigns/{campaignId}/metrics/retention-weekly:
1866
+ get:
1867
+ operationId: getCampaignRetentionWeekly
1868
+ summary: Campaign weekly cohort retention
1869
+ description: |
1870
+ Weekly cohort retention for attributed plays (listeners who reached the campaign
1871
+ soundlink), read from `api_campaign_cohort_retention_weekly_by_country`. Cohort
1872
+ weeks are UTC and anchored on the campaign start, not calendar Mondays. Each
1873
+ listener has one acquisition country.
1874
+
1875
+ `days` covers relative days 0 to 7. `weeks` covers relative weeks 0 to 26; week N
1876
+ spans days `7N` to `7N+6` (week 0 `streams` includes day 0). Week 0 `pct` is the
1877
+ share of the cohort active on days 1 to 6 (day 0 excluded).
1878
+
1879
+ Only fully observed days and weeks are returned. Young cohorts have shorter,
1880
+ possibly empty arrays, and cells are never padded.
1881
+
1882
+ Omit `groupBy` for the global rollup (`country_code` is `null`; counts are summed
1883
+ over countries and `pct` is recomputed). `groupBy=country` returns one item per
1884
+ cohort week and country (`XX` when unknown).
1885
+
1886
+ `startDate` / `endDate` filter `cohort_week` (inclusive) and default to a recent
1887
+ window. A range that is too wide returns `400 invalid_query_parameter`.
1888
+
1889
+ **Plan requirement:** Label, Enterprise, committed, and self-serve plans.
1890
+ Organizations on a lower plan receive `403 premium_plan_required`.
1891
+
1892
+ Requires the `metrics:read` scope. A campaign outside the organization returns
1893
+ `404 campaign_not_found`.
1894
+ tags: [Metrics]
1895
+ security:
1896
+ - apiKeyBearerAuth: []
1897
+ - oauthBearer: []
1898
+ x-required-scope: metrics:read
1899
+ x-premium-plan-level-min: 3
1900
+ parameters:
1901
+ - $ref: '#/components/parameters/campaignId'
1902
+ - $ref: '#/components/parameters/startDate'
1903
+ - $ref: '#/components/parameters/endDate'
1904
+ - name: groupBy
1905
+ in: query
1906
+ required: false
1907
+ schema:
1908
+ type: string
1909
+ enum: [country]
1910
+ responses:
1911
+ '200':
1912
+ description: Weekly cohort retention items, sorted by `cohort_week` (then `country_code` when grouped).
1913
+ content:
1914
+ application/json:
1915
+ schema:
1916
+ $ref: '#/components/schemas/CohortRetentionWeeklyResponse'
1917
+ '400': { $ref: '#/components/responses/BadRequest' }
1918
+ '401': { $ref: '#/components/responses/Unauthorized' }
1919
+ '403': { $ref: '#/components/responses/PremiumAnalyticsForbidden' }
1920
+ '404': { $ref: '#/components/responses/NotFound' }
1921
+ '429': { $ref: '#/components/responses/RateLimited' }
1922
+ '500': { $ref: '#/components/responses/InternalError' }
1923
+
1710
1924
  /v1/campaigns/{campaignId}/listening-insights/{insight}:
1711
1925
  get:
1712
1926
  operationId: getCampaignListeningInsight
@@ -2005,14 +2219,16 @@ paths:
2005
2219
  /v1/soundlinks/{soundlinkId}/test-events:
2006
2220
  post:
2007
2221
  operationId: sendSoundlinkTestEvents
2008
- summary: Send a test conversion event for a soundlink
2222
+ summary: Send test conversion events for a soundlink
2009
2223
  description: |
2010
2224
  Sends the same test conversion event as the in-app "send test event"
2011
2225
  action. Pixels and tokens are read from the soundlink. This request
2012
2226
  has no body.
2013
2227
 
2014
- When the soundlink has a Meta pixel, a live Meta Conversions API event
2015
- named `Soundlink Stream` is sent to that pixel. When it has a TikTok
2228
+ When the soundlink has a Meta pixel, live Meta Conversions API events
2229
+ named `Soundlink Auth`, `Soundlink Stream`, `Soundlink Stream Value`
2230
+ (value 0 USD), `Soundlink Follower`, and `Soundlink Artist Follower`
2231
+ are sent to that pixel in one request. When it has a TikTok
2016
2232
  pixel, a live TikTok `ViewContent` event is sent as well. These are
2017
2233
  not sandbox events: they appear in the ad platform's events manager.
2018
2234
 
@@ -2462,9 +2678,8 @@ paths:
2462
2678
  plays (dates with no first plays have no row), where the cohort date is
2463
2679
  the UTC date listeners first played via the soundlink. A listener's
2464
2680
  cohort date is their earliest first play across all countries.
2465
- Conforms to the `soundlink_cohort_retention_daily` v1.0 schema. All rows
2466
- are returned in `data.items` (one per cohort date), so there is no
2467
- pagination.
2681
+ Conforms to the `soundlink_cohort_retention_daily` v1.1 schema. All rows
2682
+ are returned in `data.items`, so there is no pagination.
2468
2683
 
2469
2684
  **Retention definitions:**
2470
2685
  - `returned_on_day_N`: listeners from the cohort who played again on exactly day N
@@ -2472,8 +2687,13 @@ paths:
2472
2687
  - `retention_by_day_N`: share of the cohort (`cohort_size`) who played again on any
2473
2688
  day from 1 to N (end-day, cumulative). Each listener is counted once, so the
2474
2689
  by-day rate never decreases within a row.
2690
+ - `streams_on_day_N`: attributed plays on exactly day N after first play.
2475
2691
  - A day-N value is `null` until day N has passed for that cohort date.
2476
2692
 
2693
+ Omit `groupBy` for the global rollup (`country_code` is `null`; counts are summed
2694
+ over acquisition countries and rates are recomputed). `groupBy=country` returns one
2695
+ item per cohort date and acquisition country (`XX` when unknown).
2696
+
2477
2697
  **Known limitation:** end-day rates are cumulative per listener, so whether
2478
2698
  day-3 returners also returned on day 2 is not recoverable from the end-day
2479
2699
  columns. Use the exact-day `returned_on_day_N` columns for day-by-day behaviour.
@@ -2498,9 +2718,15 @@ paths:
2498
2718
  - $ref: '#/components/parameters/soundlinkId'
2499
2719
  - $ref: '#/components/parameters/startDate'
2500
2720
  - $ref: '#/components/parameters/endDate'
2721
+ - name: groupBy
2722
+ in: query
2723
+ required: false
2724
+ schema:
2725
+ type: string
2726
+ enum: [country]
2501
2727
  responses:
2502
2728
  '200':
2503
- description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` ascending.
2729
+ description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` (then `country_code` when grouped).
2504
2730
  content:
2505
2731
  application/json:
2506
2732
  schema:
@@ -2512,6 +2738,65 @@ paths:
2512
2738
  '429': { $ref: '#/components/responses/RateLimited' }
2513
2739
  '500': { $ref: '#/components/responses/InternalError' }
2514
2740
 
2741
+ /v1/soundlinks/{soundlinkId}/metrics/retention-weekly:
2742
+ get:
2743
+ operationId: getSoundlinkRetentionWeekly
2744
+ summary: Soundlink weekly cohort retention
2745
+ description: |
2746
+ Weekly cohort retention for attributed plays (listeners who reached the
2747
+ soundlink), read from `api_smart_link_cohort_retention_weekly_by_country`. Cohort
2748
+ weeks are UTC and anchored on the soundlink creation date, not calendar Mondays.
2749
+ Each listener has one acquisition country.
2750
+
2751
+ `days` covers relative days 0 to 7. `weeks` covers relative weeks 0 to 26; week N
2752
+ spans days `7N` to `7N+6` (week 0 `streams` includes day 0). Week 0 `pct` is the
2753
+ share of the cohort active on days 1 to 6 (day 0 excluded).
2754
+
2755
+ Only fully observed days and weeks are returned. Young cohorts have shorter,
2756
+ possibly empty arrays, and cells are never padded.
2757
+
2758
+ Omit `groupBy` for the global rollup (`country_code` is `null`; counts are summed
2759
+ over countries and `pct` is recomputed). `groupBy=country` returns one item per
2760
+ cohort week and country (`XX` when unknown).
2761
+
2762
+ `startDate` / `endDate` filter `cohort_week` (inclusive) and default to a recent
2763
+ window. A range that is too wide returns `400 invalid_query_parameter`.
2764
+
2765
+ **Plan requirement:** Label, Enterprise, committed, and self-serve plans.
2766
+ Organizations on a lower plan receive `403 premium_plan_required`.
2767
+
2768
+ Requires the `soundlinks:read` scope. A soundlink outside the organization returns
2769
+ `404 not_found`.
2770
+ tags: [Soundlinks]
2771
+ security:
2772
+ - apiKeyBearerAuth: []
2773
+ - oauthBearer: []
2774
+ x-required-scope: soundlinks:read
2775
+ x-premium-plan-level-min: 3
2776
+ parameters:
2777
+ - $ref: '#/components/parameters/soundlinkId'
2778
+ - $ref: '#/components/parameters/startDate'
2779
+ - $ref: '#/components/parameters/endDate'
2780
+ - name: groupBy
2781
+ in: query
2782
+ required: false
2783
+ schema:
2784
+ type: string
2785
+ enum: [country]
2786
+ responses:
2787
+ '200':
2788
+ description: Weekly cohort retention items, sorted by `cohort_week` (then `country_code` when grouped).
2789
+ content:
2790
+ application/json:
2791
+ schema:
2792
+ $ref: '#/components/schemas/CohortRetentionWeeklyResponse'
2793
+ '400': { $ref: '#/components/responses/BadRequest' }
2794
+ '401': { $ref: '#/components/responses/Unauthorized' }
2795
+ '403': { $ref: '#/components/responses/PremiumAnalyticsForbidden' }
2796
+ '404': { $ref: '#/components/responses/NotFound' }
2797
+ '429': { $ref: '#/components/responses/RateLimited' }
2798
+ '500': { $ref: '#/components/responses/InternalError' }
2799
+
2515
2800
  /v1/soundlinks/{soundlinkId}/listening-insights/{insight}:
2516
2801
  get:
2517
2802
  operationId: getSoundlinkListeningInsight
@@ -3121,7 +3406,6 @@ components:
3121
3406
  - wallet_not_enabled
3122
3407
  - premium_plan_required
3123
3408
  - soundlink_plan_required
3124
- - stream_value_not_enabled
3125
3409
  - custom_pixel_not_enabled
3126
3410
  - meta_pixel_conflict
3127
3411
  - pixel_in_use
@@ -3404,6 +3688,64 @@ components:
3404
3688
  meta:
3405
3689
  $ref: '#/components/schemas/Meta'
3406
3690
 
3691
+ CampaignActivityBatchRequest:
3692
+ type: object
3693
+ required: [campaignIds]
3694
+ properties:
3695
+ campaignIds:
3696
+ type: array
3697
+ minItems: 1
3698
+ maxItems: 50
3699
+ items:
3700
+ type: string
3701
+ minLength: 1
3702
+ description: Campaign IDs to fetch. Duplicates are ignored. Max 50.
3703
+ page:
3704
+ type: integer
3705
+ minimum: 1
3706
+ default: 1
3707
+ description: Page number (1-indexed). Applied to every campaign.
3708
+ pageSize:
3709
+ type: integer
3710
+ minimum: 1
3711
+ maximum: 100
3712
+ default: 20
3713
+ description: Items per page (max 100). Applied to every campaign.
3714
+ startDate:
3715
+ type: string
3716
+ description: |
3717
+ Return events at or after this moment for every campaign.
3718
+ `YYYY-MM-DD` starts at 00:00:00Z. An ISO-8601 timestamp uses that
3719
+ instant.
3720
+
3721
+ CampaignActivityBatchItem:
3722
+ type: object
3723
+ required: [campaignId, items, pagination]
3724
+ properties:
3725
+ campaignId:
3726
+ type: string
3727
+ items:
3728
+ type: array
3729
+ items:
3730
+ $ref: '#/components/schemas/CampaignActivityItem'
3731
+ pagination:
3732
+ $ref: '#/components/schemas/Pagination'
3733
+
3734
+ CampaignActivityBatchResponse:
3735
+ type: object
3736
+ required: [data, meta]
3737
+ properties:
3738
+ data:
3739
+ type: object
3740
+ required: [items]
3741
+ properties:
3742
+ items:
3743
+ type: array
3744
+ items:
3745
+ $ref: '#/components/schemas/CampaignActivityBatchItem'
3746
+ meta:
3747
+ $ref: '#/components/schemas/Meta'
3748
+
3407
3749
  TierStatusUpdateItem:
3408
3750
  type: object
3409
3751
  required: [targetingTierId, isEnabled, newAllocationPercent]
@@ -3935,6 +4277,51 @@ components:
3935
4277
  meta:
3936
4278
  $ref: '#/components/schemas/Meta'
3937
4279
 
4280
+ CampaignMetricsOverviewBatchRequest:
4281
+ type: object
4282
+ required: [campaignIds]
4283
+ properties:
4284
+ campaignIds:
4285
+ type: array
4286
+ minItems: 1
4287
+ maxItems: 50
4288
+ items:
4289
+ type: string
4290
+ minLength: 1
4291
+ description: Campaign IDs to fetch. Duplicates are ignored. Max 50.
4292
+ startDate:
4293
+ type: string
4294
+ format: date
4295
+ description: Inclusive start date (YYYY-MM-DD). Optional.
4296
+ endDate:
4297
+ type: string
4298
+ format: date
4299
+ description: Inclusive end date (YYYY-MM-DD). Optional.
4300
+
4301
+ MetricsOverviewBatchItem:
4302
+ allOf:
4303
+ - type: object
4304
+ required: [campaignId]
4305
+ properties:
4306
+ campaignId:
4307
+ type: string
4308
+ - $ref: '#/components/schemas/MetricsOverview'
4309
+
4310
+ CampaignMetricsOverviewBatchResponse:
4311
+ type: object
4312
+ required: [data, meta]
4313
+ properties:
4314
+ data:
4315
+ type: object
4316
+ required: [items]
4317
+ properties:
4318
+ items:
4319
+ type: array
4320
+ items:
4321
+ $ref: '#/components/schemas/MetricsOverviewBatchItem'
4322
+ meta:
4323
+ $ref: '#/components/schemas/Meta'
4324
+
3938
4325
  CreativeMetricsChild:
3939
4326
  type: object
3940
4327
  required:
@@ -3950,6 +4337,7 @@ components:
3950
4337
  - cpf
3951
4338
  - cpc_linkclick
3952
4339
  - frequency
4340
+ - delivery_state
3953
4341
  properties:
3954
4342
  caption:
3955
4343
  type: string
@@ -3995,6 +4383,15 @@ components:
3995
4383
  frequency:
3996
4384
  type: number
3997
4385
  nullable: true
4386
+ delivery_state:
4387
+ type: string
4388
+ nullable: true
4389
+ enum: [disapproved]
4390
+ description: |
4391
+ `disapproved` when this child uses a partner-uploaded
4392
+ (`user_upload`) background video and at least one linked Meta ad
4393
+ has `effective_status` DISAPPROVED. Otherwise `null` (catalog
4394
+ videos, non-disapproved ads, or status not yet synced).
3998
4395
 
3999
4396
  CreativeMetricsGroup:
4000
4397
  type: object
@@ -4062,6 +4459,45 @@ components:
4062
4459
  meta:
4063
4460
  $ref: '#/components/schemas/Meta'
4064
4461
 
4462
+ CampaignMetricsCreativesBatchRequest:
4463
+ type: object
4464
+ required: [campaignIds]
4465
+ properties:
4466
+ campaignIds:
4467
+ type: array
4468
+ minItems: 1
4469
+ maxItems: 50
4470
+ items:
4471
+ type: string
4472
+ minLength: 1
4473
+ description: Campaign IDs to fetch. Duplicates are ignored. Max 50.
4474
+
4475
+ CreativeMetricsBatchItem:
4476
+ type: object
4477
+ required: [campaignId, creatives]
4478
+ properties:
4479
+ campaignId:
4480
+ type: string
4481
+ creatives:
4482
+ type: array
4483
+ items:
4484
+ $ref: '#/components/schemas/CreativeMetricsGroup'
4485
+
4486
+ CampaignMetricsCreativesBatchResponse:
4487
+ type: object
4488
+ required: [data, meta]
4489
+ properties:
4490
+ data:
4491
+ type: object
4492
+ required: [items]
4493
+ properties:
4494
+ items:
4495
+ type: array
4496
+ items:
4497
+ $ref: '#/components/schemas/CreativeMetricsBatchItem'
4498
+ meta:
4499
+ $ref: '#/components/schemas/Meta'
4500
+
4065
4501
  CreativeDailyMetricsRow:
4066
4502
  type: object
4067
4503
  required:
@@ -4574,7 +5010,7 @@ components:
4574
5010
  description: |
4575
5011
  Meta pixel ID. Send with `metaConversionAccessToken` to save or
4576
5012
  rotate the token (unchanged). Or send `metaPixelId` alone to reuse
4577
- a pixel the organization already saved (requires pixel settings).
5013
+ a pixel the organization already saved.
4578
5014
  Omit both to skip Meta tracking. Never applies an org default.
4579
5015
  metaConversionAccessToken:
4580
5016
  type: string
@@ -5104,12 +5540,19 @@ components:
5104
5540
  properties:
5105
5541
  data:
5106
5542
  type: object
5107
- required: [schemaVersion, items]
5543
+ required: [schemaVersion, groupBy, items]
5108
5544
  properties:
5109
5545
  schemaVersion:
5110
5546
  type: string
5111
5547
  description: Version of the `soundlink_cohort_retention_daily` row schema. Pin your ingest pipeline to this.
5112
- example: '1.0'
5548
+ example: '1.1'
5549
+ groupBy:
5550
+ type: string
5551
+ nullable: true
5552
+ enum: [country]
5553
+ description: |
5554
+ `null` when `groupBy` is omitted (global rollup). `country` when
5555
+ `groupBy=country`.
5113
5556
  items:
5114
5557
  type: array
5115
5558
  items:
@@ -5117,11 +5560,106 @@ components:
5117
5560
  meta:
5118
5561
  $ref: '#/components/schemas/Meta'
5119
5562
 
5563
+ CohortRetentionWeeklyResponse:
5564
+ type: object
5565
+ required: [data, meta]
5566
+ properties:
5567
+ data:
5568
+ type: object
5569
+ required: [schemaVersion, granularity, scope, groupBy, items]
5570
+ properties:
5571
+ schemaVersion:
5572
+ type: string
5573
+ example: '1.0'
5574
+ granularity:
5575
+ type: string
5576
+ enum: [week]
5577
+ scope:
5578
+ type: string
5579
+ enum: [attributed]
5580
+ groupBy:
5581
+ type: string
5582
+ nullable: true
5583
+ enum: [country]
5584
+ items:
5585
+ type: array
5586
+ items:
5587
+ $ref: '#/components/schemas/CohortRetentionWeeklyItem'
5588
+ meta:
5589
+ $ref: '#/components/schemas/Meta'
5590
+
5591
+ CohortRetentionWeeklyItem:
5592
+ type: object
5593
+ required:
5594
+ [
5595
+ soundlink_id,
5596
+ cohort_week,
5597
+ cohort_week_timezone,
5598
+ country_code,
5599
+ cohort_size,
5600
+ days,
5601
+ weeks,
5602
+ ]
5603
+ properties:
5604
+ soundlink_id:
5605
+ type: string
5606
+ cohort_week:
5607
+ type: string
5608
+ format: date
5609
+ cohort_week_timezone:
5610
+ type: string
5611
+ enum: [UTC]
5612
+ country_code:
5613
+ type: string
5614
+ nullable: true
5615
+ description: Acquisition country (`XX` if unknown). `null` for the global rollup.
5616
+ cohort_size:
5617
+ type: integer
5618
+ days:
5619
+ type: array
5620
+ items:
5621
+ $ref: '#/components/schemas/CohortRetentionWeeklyDayCell'
5622
+ weeks:
5623
+ type: array
5624
+ items:
5625
+ $ref: '#/components/schemas/CohortRetentionWeeklyWeekCell'
5626
+
5627
+ CohortRetentionWeeklyDayCell:
5628
+ type: object
5629
+ required: [day, active_users, pct, streams]
5630
+ properties:
5631
+ day:
5632
+ type: integer
5633
+ minimum: 0
5634
+ maximum: 7
5635
+ active_users:
5636
+ type: integer
5637
+ pct:
5638
+ type: number
5639
+ streams:
5640
+ type: integer
5641
+
5642
+ CohortRetentionWeeklyWeekCell:
5643
+ type: object
5644
+ required: [week, active_users, pct, streams]
5645
+ properties:
5646
+ week:
5647
+ type: integer
5648
+ minimum: 0
5649
+ maximum: 26
5650
+ active_users:
5651
+ type: integer
5652
+ pct:
5653
+ type: number
5654
+ streams:
5655
+ type: integer
5656
+
5120
5657
  SoundlinkCohortRetentionDailyRow:
5121
5658
  type: object
5122
5659
  description: |
5123
- One row of the `soundlink_cohort_retention_daily` v1.0 schema.
5124
- Primary key: `(provider, account_id, cohort_date, soundlink_id)`.
5660
+ One row of the `soundlink_cohort_retention_daily` v1.1 schema.
5661
+ Primary key (global): `(provider, account_id, cohort_date, soundlink_id)`.
5662
+ Primary key (`groupBy=country`): add `country_code`.
5125
5663
  Rows are idempotent. Re-ingesting on the primary key is safe.
5126
5664
  A day-N value is final once day N has passed for the cohort date.
5127
5665
  Until then it is `null`.
@@ -5135,21 +5673,29 @@ components:
5135
5673
  - soundlink_id
5136
5674
  - soundlink_name
5137
5675
  - soundlink_target_type
5676
+ - country_code
5138
5677
  - cohort_size
5139
5678
  - returned_on_day_1
5140
5679
  - retention_by_day_1
5680
+ - streams_on_day_1
5141
5681
  - returned_on_day_2
5142
5682
  - retention_by_day_2
5683
+ - streams_on_day_2
5143
5684
  - returned_on_day_3
5144
5685
  - retention_by_day_3
5686
+ - streams_on_day_3
5145
5687
  - returned_on_day_4
5146
5688
  - retention_by_day_4
5689
+ - streams_on_day_4
5147
5690
  - returned_on_day_5
5148
5691
  - retention_by_day_5
5692
+ - streams_on_day_5
5149
5693
  - returned_on_day_6
5150
5694
  - retention_by_day_6
5695
+ - streams_on_day_6
5151
5696
  - returned_on_day_7
5152
5697
  - retention_by_day_7
5698
+ - streams_on_day_7
5153
5699
  properties:
5154
5700
  provider:
5155
5701
  type: string
@@ -5161,7 +5707,7 @@ components:
5161
5707
  schema_version:
5162
5708
  type: string
5163
5709
  description: Schema version string. Pin your ingest pipeline to this value.
5164
- example: '1.0'
5710
+ example: '1.1'
5165
5711
  cohort_date:
5166
5712
  type: string
5167
5713
  format: date
@@ -5198,6 +5744,12 @@ components:
5198
5744
  type: string
5199
5745
  nullable: true
5200
5746
  description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
5747
+ country_code:
5748
+ type: string
5749
+ nullable: true
5750
+ description: |
5751
+ Acquisition country (country of the listener's earliest first play).
5752
+ `null` on the global rollup. `XX` when unknown in country mode.
5201
5753
  cohort_size:
5202
5754
  type: integer
5203
5755
  minimum: 0
@@ -5213,6 +5765,11 @@ components:
5213
5765
  minimum: 0
5214
5766
  maximum: 1
5215
5767
  description: Share of `cohort_size` who played again on any day from 1 to 1 (end-day, cumulative), rounded to 4 decimals. `null` until day 1 has passed.
5768
+ streams_on_day_1:
5769
+ type: integer
5770
+ nullable: true
5771
+ minimum: 0
5772
+ description: Attributed plays on exactly day 1 after first play. `null` until day 1 has passed.
5216
5773
  returned_on_day_2:
5217
5774
  type: integer
5218
5775
  nullable: true
@@ -5224,6 +5781,11 @@ components:
5224
5781
  minimum: 0
5225
5782
  maximum: 1
5226
5783
  description: Share of `cohort_size` who played again on any day from 1 to 2 (end-day, cumulative), rounded to 4 decimals. `null` until day 2 has passed.
5784
+ streams_on_day_2:
5785
+ type: integer
5786
+ nullable: true
5787
+ minimum: 0
5788
+ description: Attributed plays on exactly day 2 after first play. `null` until day 2 has passed.
5227
5789
  returned_on_day_3:
5228
5790
  type: integer
5229
5791
  nullable: true
@@ -5235,6 +5797,11 @@ components:
5235
5797
  minimum: 0
5236
5798
  maximum: 1
5237
5799
  description: Share of `cohort_size` who played again on any day from 1 to 3 (end-day, cumulative), rounded to 4 decimals. `null` until day 3 has passed.
5800
+ streams_on_day_3:
5801
+ type: integer
5802
+ nullable: true
5803
+ minimum: 0
5804
+ description: Attributed plays on exactly day 3 after first play. `null` until day 3 has passed.
5238
5805
  returned_on_day_4:
5239
5806
  type: integer
5240
5807
  nullable: true
@@ -5246,6 +5813,11 @@ components:
5246
5813
  minimum: 0
5247
5814
  maximum: 1
5248
5815
  description: Share of `cohort_size` who played again on any day from 1 to 4 (end-day, cumulative), rounded to 4 decimals. `null` until day 4 has passed.
5816
+ streams_on_day_4:
5817
+ type: integer
5818
+ nullable: true
5819
+ minimum: 0
5820
+ description: Attributed plays on exactly day 4 after first play. `null` until day 4 has passed.
5249
5821
  returned_on_day_5:
5250
5822
  type: integer
5251
5823
  nullable: true
@@ -5257,6 +5829,11 @@ components:
5257
5829
  minimum: 0
5258
5830
  maximum: 1
5259
5831
  description: Share of `cohort_size` who played again on any day from 1 to 5 (end-day, cumulative), rounded to 4 decimals. `null` until day 5 has passed.
5832
+ streams_on_day_5:
5833
+ type: integer
5834
+ nullable: true
5835
+ minimum: 0
5836
+ description: Attributed plays on exactly day 5 after first play. `null` until day 5 has passed.
5260
5837
  returned_on_day_6:
5261
5838
  type: integer
5262
5839
  nullable: true
@@ -5268,6 +5845,11 @@ components:
5268
5845
  minimum: 0
5269
5846
  maximum: 1
5270
5847
  description: Share of `cohort_size` who played again on any day from 1 to 6 (end-day, cumulative), rounded to 4 decimals. `null` until day 6 has passed.
5848
+ streams_on_day_6:
5849
+ type: integer
5850
+ nullable: true
5851
+ minimum: 0
5852
+ description: Attributed plays on exactly day 6 after first play. `null` until day 6 has passed.
5271
5853
  returned_on_day_7:
5272
5854
  type: integer
5273
5855
  nullable: true
@@ -5279,6 +5861,11 @@ components:
5279
5861
  minimum: 0
5280
5862
  maximum: 1
5281
5863
  description: Share of `cohort_size` who played again on any day from 1 to 7 (end-day, cumulative), rounded to 4 decimals. `null` until day 7 has passed.
5864
+ streams_on_day_7:
5865
+ type: integer
5866
+ nullable: true
5867
+ minimum: 0
5868
+ description: Attributed plays on exactly day 7 after first play. `null` until day 7 has passed.
5282
5869
 
5283
5870
  # --- Videos ---
5284
5871