> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Data reference
> Metrics, breakdowns, refresh cadence, and limits for the Spotify Ads data source in Adriel.
## Introduction
Spotify Ads (Spotify Advertising) is Spotify's self-serve platform for audio, video, and podcast campaigns delivered to listeners across the Spotify app and web player. The connector ingests ad account, campaign, ad set, and ad performance from the Spotify Ad Analytics API, including audio-specific signals such as streams, listeners, and skips alongside standard reach and click metrics.
As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration.
To connect this data source, see [How to connect Spotify Ads to Adriel](/data-sources/o-z/spotify-ads/how-to-connect).
## Data refresh strategy
### Architecture data
Architecture covers ad accounts, campaigns, ad sets, and ads. It refreshes twice daily, at **4:00 PM UTC** and **5:00 AM UTC**.
### Reports data
Reports include daily performance for ad accounts, campaigns, ad sets, and ads.
**Real-time.** Report data is fetched from Spotify on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled cache refreshes keep historical data consistent across multiple time windows.
**Refresh schedule.** Reports refresh on three overlapping schedules:
* **5:00 PM UTC daily** — syncs the last **9 days** for ad account, campaign, ad set, and ad
* **11:40 PM and 6:40 AM UTC daily** — syncs the last **3 days** for ad account, campaign, ad set, and ad
* **7:30 AM UTC on the 1st and 15th of each month** — syncs the last **30 days** for ad account, campaign, ad set, and ad
## Architecture levels
Ad account → Campaign → Ad set → Ad
## Date range limits
The Spotify API rejects report ranges longer than 90 days, so wide date ranges are split into 90-day windows automatically. In addition, the connector enforces these maximum look-back windows per breakdown:
| Breakdown | Max range |
| --------- | --------- |
| Daily | 93 days |
| Weekly | 1 year |
| Monthly | 2 years |
## Metrics
**How to read the columns**
**Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
**API Key** in code style like `IMPRESSIONS` is the literal Spotify Ad Analytics API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
### Delivery & reach
| Metric | Description | Data type | API Key |
| ----------------------- | ------------------------------------------------------- | --------- | ------------------------- |
| Impressions | Total times the ads were displayed. | Number | `IMPRESSIONS` |
| Reach | Unique listeners who saw or heard the ad at least once. | Number | `REACH` |
| Frequency | Average impressions per reached listener. | Ratio | `FREQUENCY` |
| Streamed impressions | Impressions delivered against streamed content. | Number | `STREAMED_IMPRESSIONS` |
| Off-Spotify impressions | Impressions served outside the Spotify platform. | Number | `OFF_SPOTIFY_IMPRESSIONS` |
### Clicks & cost
Currency values are reported in each ad account's configured currency. If the ad account currency differs from the workspace currency, costs are converted using the current day's exchange rate.
| Metric | Description | Data type | API Key |
| -------- | ------------------------------ | ---------- | ---------------------------------------------- |
| Clicks | Ad clicks. | Number | `CLICKS` |
| Ad spend | Total amount spent. | Currency | `SPEND` |
| CTR | Click-through rate. | Percentage | *Adriel-computed (clicks / impressions)* |
| CPC | Cost per click. | Currency | *Adriel-computed (spend / clicks)* |
| CPM | Cost per thousand impressions. | Currency | *Adriel-computed (spend / impressions × 1000)* |
### Audio & listeners
| Metric | Description | Data type | API Key |
| ------------------------ | ---------------------------------------------- | ---------- | -------------------------------------------------------- |
| Listeners | Unique listeners reached. | Number | `LISTENERS` |
| New listeners | First-time listeners acquired. | Number | `NEW_LISTENERS` |
| Paid listens | Paid listen events. | Number | `PAID_LISTENS` |
| Paid listen reach | Unique listeners of paid content. | Number | `PAID_LISTENS_REACH` |
| Streams | Streams attributed to the ad. | Number | `STREAMS` |
| New listener streams | Streams from new listeners. | Number | `NEW_LISTENER_STREAMS` |
| Skips | Times the ad was skipped. | Number | `SKIPS` |
| Unmutes | Times a muted ad was unmuted. | Number | `UNMUTES` |
| Listener conversion rate | Listeners as a share of reach. | Percentage | *Adriel-computed (listeners / reach)* |
| Listens frequency | Impressions divided by reach. | Ratio | *Adriel-computed (impressions / reach)* |
| Paid listens frequency | Paid listens divided by impressions. | Ratio | *Adriel-computed (paid listens / impressions)* |
| Streams per user | Streams divided by listeners. | Ratio | *Adriel-computed (streams / listeners)* |
| Streams per new listener | New listener streams divided by new listeners. | Ratio | *Adriel-computed (new listener streams / new listeners)* |
### Video
| Metric | Description | Data type | API Key |
| -------------------- | ---------------------------------------------------------------------- | ---------- | --------------------------------------------- |
| Video views | Times a video ad started playing (also surfaced as Video impressions). | Number | `STARTS` |
| Video played to 25% | Plays reaching 25% of video length. | Number | `FIRST_QUARTILES` |
| Video played to 50% | Plays reaching 50% of video length. | Number | `MIDPOINTS` |
| Video played to 75% | Plays reaching 75% of video length. | Number | `THIRD_QUARTILES` |
| Video played to 100% | Plays reaching 100% of video length. | Number | `COMPLETES` |
| Video expands | Times a video ad was expanded. | Number | `VIDEO_EXPANDS` |
| CPV | Cost per video view. | Currency | *Adriel-computed (spend / video views)* |
| View rate | Video views divided by impressions. | Percentage | *Adriel-computed (video views / impressions)* |
## Breakdowns
Spotify exposes only level and date breakdowns. Demographic, geographic, and placement breakdowns (such as country, region, or device) are not available for this connector.
### Levels
| Breakdown | Description | API Key |
| ---------- | ----------------------- | --------------- |
| Ad account | Group by ad account. | `ad_account_id` |
| Campaign | Group by campaign. | `campaign` |
| Ad set | Group by ad set. | `ad_set` |
| Ad | Group by individual ad. | `ad` |
### Time & date grouping
Spotify's API returns daily records only; Adriel groups them into these views for reporting. All time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.
| Breakdown | Description |
| ------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily | Split reports by day. |
| Weekly (Start: Mon) | Split reports by ISO week, starting Monday. |
| Weekly (Start: Sun) | Split reports by week, starting Sunday. |
| Monthly | Split reports by calendar month. |
| Quarterly | Split reports by calendar quarter. |
| Yearly | Split reports by calendar year. |
## Limitations
* **No demographic, geographic, or placement breakdowns** — the connector exposes only level and date breakdowns. Fields such as country, region, DMA, platform, and hour exist in the Spotify API but are not surfaced in Adriel.
* **Daily data only from the source** — Spotify returns daily granularity; weekly and monthly views are aggregated client-side by summing the underlying daily rows.
* **90-day request window** — the Spotify API rejects report ranges longer than 90 days. Wide ranges are fetched in 90-day chunks, which can make very wide date ranges slower to load.
## API references
* Spotify Ad Analytics API v3 — base URL `https://api-partner.spotify.com/ads/v3`
* [Spotify for Developers](https://developer.spotify.com/documentation)
## See also
* [How to connect Spotify Ads to Adriel](/data-sources/o-z/spotify-ads/how-to-connect) (paired how-to)
* [The Trade Desk data reference](/data-sources/o-z/the-trade-desk/data-reference) — alternative audio and digital programmatic platform