soundlink 2.13.0 → 2.14.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
@@ -1650,10 +1790,9 @@ paths:
1650
1790
  that has first plays (dates with no first plays have no row), where the
1651
1791
  cohort date is the UTC date listeners first played via the campaign soundlink.
1652
1792
  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
1793
+ Conforms to the `soundlink_cohort_retention_daily` v1.1 schema (same row
1654
1794
  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.
1795
+ are returned in `data.items`, so there is no pagination.
1657
1796
 
1658
1797
  The campaign's `smart_link_id` is resolved from `dim_campaigns_current`
1659
1798
  before the retention query runs.
@@ -1664,8 +1803,13 @@ paths:
1664
1803
  - `retention_by_day_N`: share of the cohort (`cohort_size`) who played again on any
1665
1804
  day from 1 to N (end-day, cumulative). Each listener is counted once, so the
1666
1805
  by-day rate never decreases within a row.
1806
+ - `streams_on_day_N`: attributed plays on exactly day N after first play.
1667
1807
  - A day-N value is `null` until day N has passed for that cohort date.
1668
1808
 
1809
+ Omit `groupBy` for the global rollup (`country_code` is `null`; counts are summed
1810
+ over acquisition countries and rates are recomputed). `groupBy=country` returns one
1811
+ item per cohort date and acquisition country (`XX` when unknown).
1812
+
1669
1813
  **Known limitation:** end-day rates are cumulative per listener, so whether
1670
1814
  day-3 returners also returned on day 2 is not recoverable from the end-day
1671
1815
  columns. Use the exact-day `returned_on_day_N` columns for day-by-day behaviour.
@@ -1693,9 +1837,15 @@ paths:
1693
1837
  - $ref: '#/components/parameters/campaignId'
1694
1838
  - $ref: '#/components/parameters/startDate'
1695
1839
  - $ref: '#/components/parameters/endDate'
1840
+ - name: groupBy
1841
+ in: query
1842
+ required: false
1843
+ schema:
1844
+ type: string
1845
+ enum: [country]
1696
1846
  responses:
1697
1847
  '200':
1698
- description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` ascending.
1848
+ description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` (then `country_code` when grouped).
1699
1849
  content:
1700
1850
  application/json:
1701
1851
  schema:
@@ -1707,6 +1857,65 @@ paths:
1707
1857
  '429': { $ref: '#/components/responses/RateLimited' }
1708
1858
  '500': { $ref: '#/components/responses/InternalError' }
1709
1859
 
1860
+ /v1/campaigns/{campaignId}/metrics/retention-weekly:
1861
+ get:
1862
+ operationId: getCampaignRetentionWeekly
1863
+ summary: Campaign weekly cohort retention
1864
+ description: |
1865
+ Weekly cohort retention for attributed plays (listeners who reached the campaign
1866
+ soundlink), read from `api_campaign_cohort_retention_weekly_by_country`. Cohort
1867
+ weeks are UTC and anchored on the campaign start, not calendar Mondays. Each
1868
+ listener has one acquisition country.
1869
+
1870
+ `days` covers relative days 0 to 7. `weeks` covers relative weeks 0 to 26; week N
1871
+ spans days `7N` to `7N+6` (week 0 `streams` includes day 0). Week 0 `pct` is the
1872
+ share of the cohort active on days 1 to 6 (day 0 excluded).
1873
+
1874
+ Only fully observed days and weeks are returned. Young cohorts have shorter,
1875
+ possibly empty arrays, and cells are never padded.
1876
+
1877
+ Omit `groupBy` for the global rollup (`country_code` is `null`; counts are summed
1878
+ over countries and `pct` is recomputed). `groupBy=country` returns one item per
1879
+ cohort week and country (`XX` when unknown).
1880
+
1881
+ `startDate` / `endDate` filter `cohort_week` (inclusive) and default to a recent
1882
+ window. A range that is too wide returns `400 invalid_query_parameter`.
1883
+
1884
+ **Plan requirement:** Label, Enterprise, committed, and self-serve plans.
1885
+ Organizations on a lower plan receive `403 premium_plan_required`.
1886
+
1887
+ Requires the `metrics:read` scope. A campaign outside the organization returns
1888
+ `404 campaign_not_found`.
1889
+ tags: [Metrics]
1890
+ security:
1891
+ - apiKeyBearerAuth: []
1892
+ - oauthBearer: []
1893
+ x-required-scope: metrics:read
1894
+ x-premium-plan-level-min: 3
1895
+ parameters:
1896
+ - $ref: '#/components/parameters/campaignId'
1897
+ - $ref: '#/components/parameters/startDate'
1898
+ - $ref: '#/components/parameters/endDate'
1899
+ - name: groupBy
1900
+ in: query
1901
+ required: false
1902
+ schema:
1903
+ type: string
1904
+ enum: [country]
1905
+ responses:
1906
+ '200':
1907
+ description: Weekly cohort retention items, sorted by `cohort_week` (then `country_code` when grouped).
1908
+ content:
1909
+ application/json:
1910
+ schema:
1911
+ $ref: '#/components/schemas/CohortRetentionWeeklyResponse'
1912
+ '400': { $ref: '#/components/responses/BadRequest' }
1913
+ '401': { $ref: '#/components/responses/Unauthorized' }
1914
+ '403': { $ref: '#/components/responses/PremiumAnalyticsForbidden' }
1915
+ '404': { $ref: '#/components/responses/NotFound' }
1916
+ '429': { $ref: '#/components/responses/RateLimited' }
1917
+ '500': { $ref: '#/components/responses/InternalError' }
1918
+
1710
1919
  /v1/campaigns/{campaignId}/listening-insights/{insight}:
1711
1920
  get:
1712
1921
  operationId: getCampaignListeningInsight
@@ -2005,14 +2214,16 @@ paths:
2005
2214
  /v1/soundlinks/{soundlinkId}/test-events:
2006
2215
  post:
2007
2216
  operationId: sendSoundlinkTestEvents
2008
- summary: Send a test conversion event for a soundlink
2217
+ summary: Send test conversion events for a soundlink
2009
2218
  description: |
2010
2219
  Sends the same test conversion event as the in-app "send test event"
2011
2220
  action. Pixels and tokens are read from the soundlink. This request
2012
2221
  has no body.
2013
2222
 
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
2223
+ When the soundlink has a Meta pixel, live Meta Conversions API events
2224
+ named `Soundlink Auth`, `Soundlink Stream`, `Soundlink Stream Value`
2225
+ (value 0 USD), `Soundlink Follower`, and `Soundlink Artist Follower`
2226
+ are sent to that pixel in one request. When it has a TikTok
2016
2227
  pixel, a live TikTok `ViewContent` event is sent as well. These are
2017
2228
  not sandbox events: they appear in the ad platform's events manager.
2018
2229
 
@@ -2462,9 +2673,8 @@ paths:
2462
2673
  plays (dates with no first plays have no row), where the cohort date is
2463
2674
  the UTC date listeners first played via the soundlink. A listener's
2464
2675
  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.
2676
+ Conforms to the `soundlink_cohort_retention_daily` v1.1 schema. All rows
2677
+ are returned in `data.items`, so there is no pagination.
2468
2678
 
2469
2679
  **Retention definitions:**
2470
2680
  - `returned_on_day_N`: listeners from the cohort who played again on exactly day N
@@ -2472,8 +2682,13 @@ paths:
2472
2682
  - `retention_by_day_N`: share of the cohort (`cohort_size`) who played again on any
2473
2683
  day from 1 to N (end-day, cumulative). Each listener is counted once, so the
2474
2684
  by-day rate never decreases within a row.
2685
+ - `streams_on_day_N`: attributed plays on exactly day N after first play.
2475
2686
  - A day-N value is `null` until day N has passed for that cohort date.
2476
2687
 
2688
+ Omit `groupBy` for the global rollup (`country_code` is `null`; counts are summed
2689
+ over acquisition countries and rates are recomputed). `groupBy=country` returns one
2690
+ item per cohort date and acquisition country (`XX` when unknown).
2691
+
2477
2692
  **Known limitation:** end-day rates are cumulative per listener, so whether
2478
2693
  day-3 returners also returned on day 2 is not recoverable from the end-day
2479
2694
  columns. Use the exact-day `returned_on_day_N` columns for day-by-day behaviour.
@@ -2498,9 +2713,15 @@ paths:
2498
2713
  - $ref: '#/components/parameters/soundlinkId'
2499
2714
  - $ref: '#/components/parameters/startDate'
2500
2715
  - $ref: '#/components/parameters/endDate'
2716
+ - name: groupBy
2717
+ in: query
2718
+ required: false
2719
+ schema:
2720
+ type: string
2721
+ enum: [country]
2501
2722
  responses:
2502
2723
  '200':
2503
- description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` ascending.
2724
+ description: Cohort retention rows (`soundlink_cohort_retention_daily` schema), sorted by `cohort_date` (then `country_code` when grouped).
2504
2725
  content:
2505
2726
  application/json:
2506
2727
  schema:
@@ -2512,6 +2733,65 @@ paths:
2512
2733
  '429': { $ref: '#/components/responses/RateLimited' }
2513
2734
  '500': { $ref: '#/components/responses/InternalError' }
2514
2735
 
2736
+ /v1/soundlinks/{soundlinkId}/metrics/retention-weekly:
2737
+ get:
2738
+ operationId: getSoundlinkRetentionWeekly
2739
+ summary: Soundlink weekly cohort retention
2740
+ description: |
2741
+ Weekly cohort retention for attributed plays (listeners who reached the
2742
+ soundlink), read from `api_smart_link_cohort_retention_weekly_by_country`. Cohort
2743
+ weeks are UTC and anchored on the soundlink creation date, not calendar Mondays.
2744
+ Each listener has one acquisition country.
2745
+
2746
+ `days` covers relative days 0 to 7. `weeks` covers relative weeks 0 to 26; week N
2747
+ spans days `7N` to `7N+6` (week 0 `streams` includes day 0). Week 0 `pct` is the
2748
+ share of the cohort active on days 1 to 6 (day 0 excluded).
2749
+
2750
+ Only fully observed days and weeks are returned. Young cohorts have shorter,
2751
+ possibly empty arrays, and cells are never padded.
2752
+
2753
+ Omit `groupBy` for the global rollup (`country_code` is `null`; counts are summed
2754
+ over countries and `pct` is recomputed). `groupBy=country` returns one item per
2755
+ cohort week and country (`XX` when unknown).
2756
+
2757
+ `startDate` / `endDate` filter `cohort_week` (inclusive) and default to a recent
2758
+ window. A range that is too wide returns `400 invalid_query_parameter`.
2759
+
2760
+ **Plan requirement:** Label, Enterprise, committed, and self-serve plans.
2761
+ Organizations on a lower plan receive `403 premium_plan_required`.
2762
+
2763
+ Requires the `soundlinks:read` scope. A soundlink outside the organization returns
2764
+ `404 not_found`.
2765
+ tags: [Soundlinks]
2766
+ security:
2767
+ - apiKeyBearerAuth: []
2768
+ - oauthBearer: []
2769
+ x-required-scope: soundlinks:read
2770
+ x-premium-plan-level-min: 3
2771
+ parameters:
2772
+ - $ref: '#/components/parameters/soundlinkId'
2773
+ - $ref: '#/components/parameters/startDate'
2774
+ - $ref: '#/components/parameters/endDate'
2775
+ - name: groupBy
2776
+ in: query
2777
+ required: false
2778
+ schema:
2779
+ type: string
2780
+ enum: [country]
2781
+ responses:
2782
+ '200':
2783
+ description: Weekly cohort retention items, sorted by `cohort_week` (then `country_code` when grouped).
2784
+ content:
2785
+ application/json:
2786
+ schema:
2787
+ $ref: '#/components/schemas/CohortRetentionWeeklyResponse'
2788
+ '400': { $ref: '#/components/responses/BadRequest' }
2789
+ '401': { $ref: '#/components/responses/Unauthorized' }
2790
+ '403': { $ref: '#/components/responses/PremiumAnalyticsForbidden' }
2791
+ '404': { $ref: '#/components/responses/NotFound' }
2792
+ '429': { $ref: '#/components/responses/RateLimited' }
2793
+ '500': { $ref: '#/components/responses/InternalError' }
2794
+
2515
2795
  /v1/soundlinks/{soundlinkId}/listening-insights/{insight}:
2516
2796
  get:
2517
2797
  operationId: getSoundlinkListeningInsight
@@ -3121,7 +3401,6 @@ components:
3121
3401
  - wallet_not_enabled
3122
3402
  - premium_plan_required
3123
3403
  - soundlink_plan_required
3124
- - stream_value_not_enabled
3125
3404
  - custom_pixel_not_enabled
3126
3405
  - meta_pixel_conflict
3127
3406
  - pixel_in_use
@@ -3404,6 +3683,64 @@ components:
3404
3683
  meta:
3405
3684
  $ref: '#/components/schemas/Meta'
3406
3685
 
3686
+ CampaignActivityBatchRequest:
3687
+ type: object
3688
+ required: [campaignIds]
3689
+ properties:
3690
+ campaignIds:
3691
+ type: array
3692
+ minItems: 1
3693
+ maxItems: 50
3694
+ items:
3695
+ type: string
3696
+ minLength: 1
3697
+ description: Campaign IDs to fetch. Duplicates are ignored. Max 50.
3698
+ page:
3699
+ type: integer
3700
+ minimum: 1
3701
+ default: 1
3702
+ description: Page number (1-indexed). Applied to every campaign.
3703
+ pageSize:
3704
+ type: integer
3705
+ minimum: 1
3706
+ maximum: 100
3707
+ default: 20
3708
+ description: Items per page (max 100). Applied to every campaign.
3709
+ startDate:
3710
+ type: string
3711
+ description: |
3712
+ Return events at or after this moment for every campaign.
3713
+ `YYYY-MM-DD` starts at 00:00:00Z. An ISO-8601 timestamp uses that
3714
+ instant.
3715
+
3716
+ CampaignActivityBatchItem:
3717
+ type: object
3718
+ required: [campaignId, items, pagination]
3719
+ properties:
3720
+ campaignId:
3721
+ type: string
3722
+ items:
3723
+ type: array
3724
+ items:
3725
+ $ref: '#/components/schemas/CampaignActivityItem'
3726
+ pagination:
3727
+ $ref: '#/components/schemas/Pagination'
3728
+
3729
+ CampaignActivityBatchResponse:
3730
+ type: object
3731
+ required: [data, meta]
3732
+ properties:
3733
+ data:
3734
+ type: object
3735
+ required: [items]
3736
+ properties:
3737
+ items:
3738
+ type: array
3739
+ items:
3740
+ $ref: '#/components/schemas/CampaignActivityBatchItem'
3741
+ meta:
3742
+ $ref: '#/components/schemas/Meta'
3743
+
3407
3744
  TierStatusUpdateItem:
3408
3745
  type: object
3409
3746
  required: [targetingTierId, isEnabled, newAllocationPercent]
@@ -3935,6 +4272,51 @@ components:
3935
4272
  meta:
3936
4273
  $ref: '#/components/schemas/Meta'
3937
4274
 
4275
+ CampaignMetricsOverviewBatchRequest:
4276
+ type: object
4277
+ required: [campaignIds]
4278
+ properties:
4279
+ campaignIds:
4280
+ type: array
4281
+ minItems: 1
4282
+ maxItems: 50
4283
+ items:
4284
+ type: string
4285
+ minLength: 1
4286
+ description: Campaign IDs to fetch. Duplicates are ignored. Max 50.
4287
+ startDate:
4288
+ type: string
4289
+ format: date
4290
+ description: Inclusive start date (YYYY-MM-DD). Optional.
4291
+ endDate:
4292
+ type: string
4293
+ format: date
4294
+ description: Inclusive end date (YYYY-MM-DD). Optional.
4295
+
4296
+ MetricsOverviewBatchItem:
4297
+ allOf:
4298
+ - type: object
4299
+ required: [campaignId]
4300
+ properties:
4301
+ campaignId:
4302
+ type: string
4303
+ - $ref: '#/components/schemas/MetricsOverview'
4304
+
4305
+ CampaignMetricsOverviewBatchResponse:
4306
+ type: object
4307
+ required: [data, meta]
4308
+ properties:
4309
+ data:
4310
+ type: object
4311
+ required: [items]
4312
+ properties:
4313
+ items:
4314
+ type: array
4315
+ items:
4316
+ $ref: '#/components/schemas/MetricsOverviewBatchItem'
4317
+ meta:
4318
+ $ref: '#/components/schemas/Meta'
4319
+
3938
4320
  CreativeMetricsChild:
3939
4321
  type: object
3940
4322
  required:
@@ -4062,6 +4444,45 @@ components:
4062
4444
  meta:
4063
4445
  $ref: '#/components/schemas/Meta'
4064
4446
 
4447
+ CampaignMetricsCreativesBatchRequest:
4448
+ type: object
4449
+ required: [campaignIds]
4450
+ properties:
4451
+ campaignIds:
4452
+ type: array
4453
+ minItems: 1
4454
+ maxItems: 50
4455
+ items:
4456
+ type: string
4457
+ minLength: 1
4458
+ description: Campaign IDs to fetch. Duplicates are ignored. Max 50.
4459
+
4460
+ CreativeMetricsBatchItem:
4461
+ type: object
4462
+ required: [campaignId, creatives]
4463
+ properties:
4464
+ campaignId:
4465
+ type: string
4466
+ creatives:
4467
+ type: array
4468
+ items:
4469
+ $ref: '#/components/schemas/CreativeMetricsGroup'
4470
+
4471
+ CampaignMetricsCreativesBatchResponse:
4472
+ type: object
4473
+ required: [data, meta]
4474
+ properties:
4475
+ data:
4476
+ type: object
4477
+ required: [items]
4478
+ properties:
4479
+ items:
4480
+ type: array
4481
+ items:
4482
+ $ref: '#/components/schemas/CreativeMetricsBatchItem'
4483
+ meta:
4484
+ $ref: '#/components/schemas/Meta'
4485
+
4065
4486
  CreativeDailyMetricsRow:
4066
4487
  type: object
4067
4488
  required:
@@ -4574,7 +4995,7 @@ components:
4574
4995
  description: |
4575
4996
  Meta pixel ID. Send with `metaConversionAccessToken` to save or
4576
4997
  rotate the token (unchanged). Or send `metaPixelId` alone to reuse
4577
- a pixel the organization already saved (requires pixel settings).
4998
+ a pixel the organization already saved.
4578
4999
  Omit both to skip Meta tracking. Never applies an org default.
4579
5000
  metaConversionAccessToken:
4580
5001
  type: string
@@ -5104,12 +5525,19 @@ components:
5104
5525
  properties:
5105
5526
  data:
5106
5527
  type: object
5107
- required: [schemaVersion, items]
5528
+ required: [schemaVersion, groupBy, items]
5108
5529
  properties:
5109
5530
  schemaVersion:
5110
5531
  type: string
5111
5532
  description: Version of the `soundlink_cohort_retention_daily` row schema. Pin your ingest pipeline to this.
5112
- example: '1.0'
5533
+ example: '1.1'
5534
+ groupBy:
5535
+ type: string
5536
+ nullable: true
5537
+ enum: [country]
5538
+ description: |
5539
+ `null` when `groupBy` is omitted (global rollup). `country` when
5540
+ `groupBy=country`.
5113
5541
  items:
5114
5542
  type: array
5115
5543
  items:
@@ -5117,11 +5545,106 @@ components:
5117
5545
  meta:
5118
5546
  $ref: '#/components/schemas/Meta'
5119
5547
 
5548
+ CohortRetentionWeeklyResponse:
5549
+ type: object
5550
+ required: [data, meta]
5551
+ properties:
5552
+ data:
5553
+ type: object
5554
+ required: [schemaVersion, granularity, scope, groupBy, items]
5555
+ properties:
5556
+ schemaVersion:
5557
+ type: string
5558
+ example: '1.0'
5559
+ granularity:
5560
+ type: string
5561
+ enum: [week]
5562
+ scope:
5563
+ type: string
5564
+ enum: [attributed]
5565
+ groupBy:
5566
+ type: string
5567
+ nullable: true
5568
+ enum: [country]
5569
+ items:
5570
+ type: array
5571
+ items:
5572
+ $ref: '#/components/schemas/CohortRetentionWeeklyItem'
5573
+ meta:
5574
+ $ref: '#/components/schemas/Meta'
5575
+
5576
+ CohortRetentionWeeklyItem:
5577
+ type: object
5578
+ required:
5579
+ [
5580
+ soundlink_id,
5581
+ cohort_week,
5582
+ cohort_week_timezone,
5583
+ country_code,
5584
+ cohort_size,
5585
+ days,
5586
+ weeks,
5587
+ ]
5588
+ properties:
5589
+ soundlink_id:
5590
+ type: string
5591
+ cohort_week:
5592
+ type: string
5593
+ format: date
5594
+ cohort_week_timezone:
5595
+ type: string
5596
+ enum: [UTC]
5597
+ country_code:
5598
+ type: string
5599
+ nullable: true
5600
+ description: Acquisition country (`XX` if unknown). `null` for the global rollup.
5601
+ cohort_size:
5602
+ type: integer
5603
+ days:
5604
+ type: array
5605
+ items:
5606
+ $ref: '#/components/schemas/CohortRetentionWeeklyDayCell'
5607
+ weeks:
5608
+ type: array
5609
+ items:
5610
+ $ref: '#/components/schemas/CohortRetentionWeeklyWeekCell'
5611
+
5612
+ CohortRetentionWeeklyDayCell:
5613
+ type: object
5614
+ required: [day, active_users, pct, streams]
5615
+ properties:
5616
+ day:
5617
+ type: integer
5618
+ minimum: 0
5619
+ maximum: 7
5620
+ active_users:
5621
+ type: integer
5622
+ pct:
5623
+ type: number
5624
+ streams:
5625
+ type: integer
5626
+
5627
+ CohortRetentionWeeklyWeekCell:
5628
+ type: object
5629
+ required: [week, active_users, pct, streams]
5630
+ properties:
5631
+ week:
5632
+ type: integer
5633
+ minimum: 0
5634
+ maximum: 26
5635
+ active_users:
5636
+ type: integer
5637
+ pct:
5638
+ type: number
5639
+ streams:
5640
+ type: integer
5641
+
5120
5642
  SoundlinkCohortRetentionDailyRow:
5121
5643
  type: object
5122
5644
  description: |
5123
- One row of the `soundlink_cohort_retention_daily` v1.0 schema.
5124
- Primary key: `(provider, account_id, cohort_date, soundlink_id)`.
5645
+ One row of the `soundlink_cohort_retention_daily` v1.1 schema.
5646
+ Primary key (global): `(provider, account_id, cohort_date, soundlink_id)`.
5647
+ Primary key (`groupBy=country`): add `country_code`.
5125
5648
  Rows are idempotent. Re-ingesting on the primary key is safe.
5126
5649
  A day-N value is final once day N has passed for the cohort date.
5127
5650
  Until then it is `null`.
@@ -5135,21 +5658,29 @@ components:
5135
5658
  - soundlink_id
5136
5659
  - soundlink_name
5137
5660
  - soundlink_target_type
5661
+ - country_code
5138
5662
  - cohort_size
5139
5663
  - returned_on_day_1
5140
5664
  - retention_by_day_1
5665
+ - streams_on_day_1
5141
5666
  - returned_on_day_2
5142
5667
  - retention_by_day_2
5668
+ - streams_on_day_2
5143
5669
  - returned_on_day_3
5144
5670
  - retention_by_day_3
5671
+ - streams_on_day_3
5145
5672
  - returned_on_day_4
5146
5673
  - retention_by_day_4
5674
+ - streams_on_day_4
5147
5675
  - returned_on_day_5
5148
5676
  - retention_by_day_5
5677
+ - streams_on_day_5
5149
5678
  - returned_on_day_6
5150
5679
  - retention_by_day_6
5680
+ - streams_on_day_6
5151
5681
  - returned_on_day_7
5152
5682
  - retention_by_day_7
5683
+ - streams_on_day_7
5153
5684
  properties:
5154
5685
  provider:
5155
5686
  type: string
@@ -5161,7 +5692,7 @@ components:
5161
5692
  schema_version:
5162
5693
  type: string
5163
5694
  description: Schema version string. Pin your ingest pipeline to this value.
5164
- example: '1.0'
5695
+ example: '1.1'
5165
5696
  cohort_date:
5166
5697
  type: string
5167
5698
  format: date
@@ -5198,6 +5729,12 @@ components:
5198
5729
  type: string
5199
5730
  nullable: true
5200
5731
  description: Spotify playlist ID. Populated when `soundlink_target_type = playlist`; otherwise `null`.
5732
+ country_code:
5733
+ type: string
5734
+ nullable: true
5735
+ description: |
5736
+ Acquisition country (country of the listener's earliest first play).
5737
+ `null` on the global rollup. `XX` when unknown in country mode.
5201
5738
  cohort_size:
5202
5739
  type: integer
5203
5740
  minimum: 0
@@ -5213,6 +5750,11 @@ components:
5213
5750
  minimum: 0
5214
5751
  maximum: 1
5215
5752
  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.
5753
+ streams_on_day_1:
5754
+ type: integer
5755
+ nullable: true
5756
+ minimum: 0
5757
+ description: Attributed plays on exactly day 1 after first play. `null` until day 1 has passed.
5216
5758
  returned_on_day_2:
5217
5759
  type: integer
5218
5760
  nullable: true
@@ -5224,6 +5766,11 @@ components:
5224
5766
  minimum: 0
5225
5767
  maximum: 1
5226
5768
  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.
5769
+ streams_on_day_2:
5770
+ type: integer
5771
+ nullable: true
5772
+ minimum: 0
5773
+ description: Attributed plays on exactly day 2 after first play. `null` until day 2 has passed.
5227
5774
  returned_on_day_3:
5228
5775
  type: integer
5229
5776
  nullable: true
@@ -5235,6 +5782,11 @@ components:
5235
5782
  minimum: 0
5236
5783
  maximum: 1
5237
5784
  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.
5785
+ streams_on_day_3:
5786
+ type: integer
5787
+ nullable: true
5788
+ minimum: 0
5789
+ description: Attributed plays on exactly day 3 after first play. `null` until day 3 has passed.
5238
5790
  returned_on_day_4:
5239
5791
  type: integer
5240
5792
  nullable: true
@@ -5246,6 +5798,11 @@ components:
5246
5798
  minimum: 0
5247
5799
  maximum: 1
5248
5800
  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.
5801
+ streams_on_day_4:
5802
+ type: integer
5803
+ nullable: true
5804
+ minimum: 0
5805
+ description: Attributed plays on exactly day 4 after first play. `null` until day 4 has passed.
5249
5806
  returned_on_day_5:
5250
5807
  type: integer
5251
5808
  nullable: true
@@ -5257,6 +5814,11 @@ components:
5257
5814
  minimum: 0
5258
5815
  maximum: 1
5259
5816
  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.
5817
+ streams_on_day_5:
5818
+ type: integer
5819
+ nullable: true
5820
+ minimum: 0
5821
+ description: Attributed plays on exactly day 5 after first play. `null` until day 5 has passed.
5260
5822
  returned_on_day_6:
5261
5823
  type: integer
5262
5824
  nullable: true
@@ -5268,6 +5830,11 @@ components:
5268
5830
  minimum: 0
5269
5831
  maximum: 1
5270
5832
  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.
5833
+ streams_on_day_6:
5834
+ type: integer
5835
+ nullable: true
5836
+ minimum: 0
5837
+ description: Attributed plays on exactly day 6 after first play. `null` until day 6 has passed.
5271
5838
  returned_on_day_7:
5272
5839
  type: integer
5273
5840
  nullable: true
@@ -5279,6 +5846,11 @@ components:
5279
5846
  minimum: 0
5280
5847
  maximum: 1
5281
5848
  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.
5849
+ streams_on_day_7:
5850
+ type: integer
5851
+ nullable: true
5852
+ minimum: 0
5853
+ description: Attributed plays on exactly day 7 after first play. `null` until day 7 has passed.
5282
5854
 
5283
5855
  # --- Videos ---
5284
5856