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 columnsData type uses Adriel’s 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; italic marks a value Adriel computes or derives on its side rather than a single API field. Some raw fields back several metrics — for example STARTS backs both Video Impressions and Views, and LISTENERS / REACH back the listener-rate metric — so the same key can appear on multiple rows; that’s the shared source field, not a duplicated entry. Currency values are reported in each ad account’s configured Spotify Ads currency.

Campaign Attributes

Metric	Description	Data type	API Key
Active Status	Whether the campaign, ad set, or ad is currently active.	Text	Adriel-side
Ad Account Name	Name of the Spotify ad account.	Text	`name`
Ad Name	Name of the ad.	Text	`name`
Ad Set Name	Name of the ad set.	Text	`name`
Ad Spend	Total amount spent on the campaign.	Currency	`SPEND`
Bid Cap	Maximum bid amount configured for the ad set.	Currency	Adriel-side
Bid Strategy	Bid strategy applied to the ad set.	Text	`bid_strategy`
Budget	Budget configured for the ad set, including whether it is a daily or lifetime budget.	Text	`budget`
Campaign Name	Name of the campaign.	Text	`name`
Creative Type	Creative format classification for the ad.	Text	Adriel-derived
Creative URL	Creative media URL for the ad when the connector has a populated creative asset to display.	Text	Adriel-side
Daily Budget	Daily budget amount set on the ad set when the budget type is daily.	Currency	`budget.type`, `budget.micro_amount`
Ends	End date scheduled for the ad set.	Date	`end_time`
Landing URL	Destination URL associated with the ad, when available.	Text	Adriel-side
Lifetime Budget	Lifetime budget amount set on the ad set when the budget type is lifetime.	Currency	`budget.type`, `budget.micro_amount`
Objective	Marketing objective configured for the campaign.	Text	Adriel-side
Starts	Start date scheduled for the ad set.	Date	`start_time`
Status (Text)	A human-readable label for the current delivery status.	Text	Adriel-side
Status (Toggle)	Current delivery or review status of the campaign, ad set, or ad.	Text	`status`
UTM Campaign	UTM campaign values associated with the ad, when available.	Text	Adriel-side
UTM Content	UTM content values associated with the ad, when available.	Text	Adriel-side
UTM Medium	UTM medium values associated with the ad, when available.	Text	Adriel-side
UTM Source	UTM source values associated with the ad, when available.	Text	Adriel-side
UTM Term	UTM term values associated with the ad, when available.	Text	Adriel-side

Campaign Structure

Metric	Description	Data type	API Key
Ad Account ID	Spotify ad account ID.	Text	`id`
Ad ID	Spotify ad ID.	Text	`id`
Ad Set ID	Spotify ad set ID.	Text	`id`
Campaign ID	Spotify campaign ID.	Text	`id`
Channel	Marketing channel classification applied for cross-connector rollup.	Text	Adriel-side

Click Performance

Currency conversion. Each ad account’s currency comes from its Spotify Ads settings. When an ad account’s currency differs from the workspace currency, costs are automatically converted using the current day’s exchange rate.

Metric	Description	Data type	API Key
CPC	Cost per click — spend divided by clicks.	Currency	Adriel-computed
CPM	Cost per thousand impressions.	Currency	Adriel-computed
CTR	Click-through rate — clicks divided by impressions.	Percentage	Adriel-computed
Impressions	Number of times the ad was served.	Number	`IMPRESSIONS`
Link Clicks	Number of times the ad was clicked.	Number	`CLICKS`
Reach	Number of unique users who received the ad.	Number	`REACH`

Computed Metrics

These are calculated by Adriel from other metrics; they have no single underlying Spotify Ads field.

Metric	Description	Data type	API Key
Frequency	Average number of impressions served per reached user (impressions divided by reach).	Ratio	Adriel-computed
Video Played To 100% (%)	Plays reaching 100% of video length as a share of video views.	Percentage	Adriel-computed
Video Played To 25% (%)	Plays reaching 25% of video length as a share of video views.	Percentage	Adriel-computed
Video Played To 50% (%)	Plays reaching 50% of video length as a share of video views.	Percentage	Adriel-computed
Video Played To 75% (%)	Plays reaching 75% of video length as a share of video views.	Percentage	Adriel-computed
View Rate	Video views divided by impressions.	Percentage	Adriel-computed

Conversion Performance

Metric	Description	Data type	API Key
Result Indicator	The metric used to represent the result for the campaign’s objective.	Text	Adriel-derived
Results	Result summary reported for the campaign’s configured objective.	Text	Adriel-derived

Creative Attributes

Metric	Description	Data type	API Key
Creative Image	A reference to the ad’s creative image.	Text	Adriel-side

Engagement

Metric	Description	Data type	API Key
Video Impressions	Number of times a user started hearing or viewing the ad.	Number	`STARTS`

Video Performance

Metric	Description	Data type	API Key
Video Played To 100% (Views)	Number of ads that played to the end.	Number	`COMPLETES`
Video Played To 25% (Views)	Number of ads that played at least 25% of the way through.	Number	`FIRST_QUARTILES`
Video Played To 50% (Views)	Number of ads that played at least 50% of the way through.	Number	`MIDPOINTS`
Video Played To 75% (Views)	Number of ads that played at least 75% of the way through.	Number	`THIRD_QUARTILES`
Views	Number of times a user started hearing or viewing the ad.	Number	`STARTS`

Spotify Ads-specific

These metrics exist only for Spotify Ads and aren’t part of any cross-connector category. Every group above is a standard category shared with other connectors.

Metric	Description	Data type	API Key
Ad Spend	Total amount spent, in the ad account’s configured currency.	Currency	Adriel-side
Listener Conversion Rate	Percentage of reached users who became listeners after seeing or hearing the ad.	Percentage	`LISTENERS`, `REACH`
Listeners	Number of listeners generated after users saw or heard the ad.	Number	`LISTENERS`
Listens Frequency	Average number of impressions served per reached user.	Ratio	`IMPRESSIONS`, `REACH`
New Listener Streams	Number of streams from new listeners who saw or heard the ad.	Number	`NEW_LISTENER_STREAMS`
New Listeners	Number of new listeners generated after users saw or heard the ad.	Number	`NEW_LISTENERS`
Off Spotify Impressions	Impressions served outside the Spotify platform.	Number	`OFF_SPOTIFY_IMPRESSIONS`
Paid Listen Reach	Number of unique users who had a paid listen on a CPCL campaign. Applies to active audio CPCL campaigns only.	Number	`PAID_LISTENS_REACH`
Paid Listens	Number of listens on a CPCL campaign where the user did not skip the ad. Applies to active audio CPCL campaigns only.	Number	`PAID_LISTENS`
Paid Listens Frequency	Average number of paid listens per impression, based on Adriel’s Spotify calculation.	Ratio	`PAID_LISTENS`, `IMPRESSIONS`
Skips	Number of times a user skipped the ad.	Number	`SKIPS`
Streamed Impressions	Number of times the ad was streamed.	Number	`STREAMED_IMPRESSIONS`
Streams	Number of streams generated after users saw or heard the ad.	Number	`STREAMS`
Streams Per New Listener	Average number of streams generated per new listener after seeing or hearing the ad.	Ratio	`NEW_LISTENER_STREAMS`, `NEW_LISTENERS`
Streams Per User	Average number of streams generated per listener after seeing or hearing the ad.	Ratio	`STREAMS`, `LISTENERS`
Unmutes	Number of times a user unmuted the ad.	Number	`UNMUTES`
Video Expands	Number of times someone expanded the ad.	Number	`VIDEO_EXPANDS`

Breakdowns

Campaign Structure

Channel, Platform, and Status groupings are provided by Adriel for cross-connector consistency rather than returned by Spotify.

Breakdown	Description	API Key
Ad	Break down results by ad name.	`name`
Ad Account	Break down results by Spotify ad account name.	`name`
Ad Name	Groups results by ad name.	Adriel-side
Ad Set	Break down results by ad set name.	`name`
Ad Set Name	Groups results by ad set name.	Adriel-side
Campaign	Break down results by campaign name.	`name`
Campaign Name	Groups results by campaign name.	Adriel-side
Channel	Break down results by marketing channel.	Adriel-side
Platform	Groups results by advertising platform.	Adriel-side
Status (Toggle)	Current delivery status of the campaign, ad set, or ad.	Adriel-side

Creatives

Adriel post-processes ad creatives to generate these breakdowns.

Breakdown	Description	API Key
Ad Copy	Word extracted from the creative text.	Adriel-side
Color Clustering	Dominant color cluster detected in the creative.	Adriel-side
Emoji Analysis	Emoji detected in the creative text or image analysis.	Adriel-side

Date

Spotify’s API returns daily records only; Adriel groups them into these views for reporting, so all time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.

Breakdown	Description	API Key
Auto Time Breakdown	Break down results by the automatically selected time interval.	Adriel-side
Daily Breakdown	Break down results by day.	`start_time`
Monthly Breakdown	Break down results by month.	Adriel-side
Quarterly Breakdown	Calendar quarter for the reported data.	Adriel-side
Week Date Breakdown	Start date of the week bucket for the reported data.	Adriel-side
Week Number Breakdown (W#)	Week number in the year for the reported data.	Adriel-side
Weekly Breakdown (Start: Mon)	Break down results by ISO week.	Adriel-side
Weekly Breakdown (Start: Sun)	Sunday-through-Saturday week bucket for the reported data.	Adriel-side
Yearly Breakdown	Calendar year for the reported data.	Adriel-side

Others

Breakdown	Description	API Key
No Grouping	Aggregate results across the full selected date range.	Adriel-side

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

​Campaign Attributes

​Campaign Structure

​Click Performance

​Computed Metrics

​Conversion Performance

​Creative Attributes

​Engagement

​Video Performance

​Spotify Ads-specific

​Breakdowns

​Campaign Structure

​Creatives

​Date

​Others

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Campaign Attributes

Campaign Structure

Click Performance

Computed Metrics

Conversion Performance

Creative Attributes

Engagement

Video Performance

Spotify Ads-specific

Breakdowns

Campaign Structure

Creatives

Date

Others

Limitations

API references

See also