Data reference - Adriel Knowledge Base

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 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

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Delivery & reach

​Clicks & cost

​Audio & listeners

​Video

​Breakdowns

​Levels

​Time & date grouping

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Delivery & reach

Clicks & cost

Audio & listeners

Video

Breakdowns

Levels

Time & date grouping

Limitations

API references

See also