Data reference

Introduction

Snapchat Ads is Snap Inc.’s advertising platform, delivering single-image, video, story, collection, and AR-lens ads across the Snapchat app, Discover, and Spotlight surfaces. It is used by performance and brand marketers to reach Snap’s predominantly younger audience with CPM, CPC, and CPV payment models across awareness, consideration, and conversion objectives. 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 Snapchat to Adriel.

Data refresh strategy

Architecture data

Architecture covers ad accounts, campaigns, ad squads (ad sets), ads, and creatives. It refreshes every 4 hours, at minute 0 (UTC). On data source creation, the cache fills with 365 days of historical data for the ad account, campaign, ad set, and ad levels.

Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad squads, and ads. Cache-only. Report data comes from cached daily performance snapshots — dashboard queries always read from the last snapshot, never live from Snapchat. Uniqueness caveat. Metrics based on uniqueness (such as reach) can be overvalued when viewed for a date period longer than one day, because uniqueness is computed per snapshot rather than across the full range. Refresh schedule. Reports refresh on this cadence:

4:00 PM UTC daily — syncs the last 30 days for the six segmentation breakdowns, each per ad account: age, location, gender, device target, country, and DMA region.
Every 10 hours, at minute 0 (UTC) — syncs the last 30 days for the campaign, ad set, and ad levels.

Data is reliable within the cache sync period. Data outside this range may be incomplete or inaccurate due to legacy caching behavior.

Architecture levels

Organization → Ad account → Campaign → Ad squad (ad set) → Ad → Creative

Date range limits

The connector enforces these maximum look-back windows to keep query sizes manageable:

Breakdown	Max range
Daily	93 days
Weekly	1 year
Monthly	2 years

Attribution windows

Snapchat conversion metrics are reported against attribution windows configured on the data source. Two windows are available:

Swipe-up (click) window — 1_DAY, 7_DAY, or 28_DAY.
View window — 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY, or 7_DAY.

An action_report_time setting further controls whether conversions are counted at conversion time or impression time. These settings are chosen when the data source is created and apply to all attributed conversion metrics.

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 Snapchat Marketing API field name. Italic text describes how a value is produced when it doesn’t map cleanly to a single API field.

Snapchat exposes roughly 100 metric columns across reach, engagement, video, and conversion categories. The most common are listed below.

Reach & impressions

Metric	Description	Data type	API Key
Impressions	Total times the ads were displayed, regardless of interaction.	Number	`impressions`
Paid impressions	Impressions from paid delivery.	Number	`paid_impressions`
Earned impressions	Impressions from earned (shared) delivery.	Number	`earned_impressions`
Total impressions	Paid and earned impressions combined.	Number	`total_impressions`
Reach	Unique users who saw the ad at least once.	Number	`total_reach`
Earned reach	Unique users reached through earned delivery.	Number	`earned_reach`
Frequency	Average impressions per unique user.	Ratio	`frequency`

Clicks & engagement

Snapchat’s primary click action is the swipe-up. The connector maps swipes to both Clicks (all) and Link clicks, and CTR is therefore a swipe-through rate.

Metric	Description	Data type	API Key
Clicks (all)	Total swipe-up actions on the ad.	Number	`swipes`
Link clicks	Swipe-up clicks to the ad destination.	Number	`swipes`
CTR	Swipe-through rate.	Percentage	Adriel-computed (swipes / impressions)
Swipe-up rate	Swipe-ups as a percentage of impressions.	Percentage	`swipe_up_percent`
Profile clicks	Clicks through to the advertiser’s public profile.	Number	`profile_clicks`
Shares	Times the ad was shared.	Number	`shares`
Saves	Times the ad was saved.	Number	`saves`
Engagement	Any user interaction with the ad, such as clicks, reactions, and shares.	Number	Aggregated from engagement events

Cost & spend

Snapchat reports spend in microcurrency (millionths of a unit); values are divided by 1,000,000 before being persisted, so dashboards always show standard currency. If the ad account’s currency differs from the workspace currency, costs are converted using the current day’s exchange rate.

Metric	Description	Data type	API Key
Ad spend	Total amount spent during the reporting period.	Currency	`spend`
CPC	Cost per click.	Currency	Adriel-computed (spend / clicks)
CPM	Cost per thousand impressions.	Currency	Adriel-computed (spend / impressions)
CPR	Cost per result.	Currency	Adriel-computed (spend / results)
eCPC	Effective cost per click.	Currency	Adriel-computed (spend / clicks)
eCPM	Effective cost per thousand impressions.	Currency	Adriel-computed ((spend × 1000) / impressions)

Video performance

Metric	Description	Data type	API Key
Views	Aggregated count of all qualified video views.	Number	`video_views`
Video played to 25%	Plays reaching 25% of video length.	Number	`quartile_1`
Video played to 50%	Plays reaching 50% of video length.	Number	`quartile_2`
Video played to 75%	Plays reaching 75% of video length.	Number	`quartile_3`
Video played to 100%	Plays reaching 100% of video length.	Number	`view_completion`
15s video views	Views lasting at least 15 seconds.	Number	`video_views_15s`
View time	Total time spent viewing the video.	Duration	`view_time_millis`
Average view time	Average video view duration.	Duration	`avg_view_time_millis`
Time-based video views	Views counted by the time-based methodology.	Number	`video_views_time_based`
Play time	Total time the video played.	Duration	`play_time_millis`
Screen time	Total time the ad occupied the screen.	Duration	`screen_time_millis`
Average screen time	Average time the ad occupied the screen.	Duration	`avg_screen_time_millis`

Attachment performance

Attachment metrics measure engagement with the attachment (for example, a swipe-up landing experience) rather than the top-level ad.

Metric	Description	Data type	API Key
Attachment impressions	Impressions of the attachment.	Number	`attachment_impressions`
Attachment unique users	Unique users who saw the attachment.	Number	`attachment_uniques`
Attachment frequency	Average attachment impressions per unique user.	Ratio	`attachment_frequency`
Attachment played to 25% / 50% / 75%	Attachment video plays reaching each threshold.	Number	`attachment_quartile_1` / `attachment_quartile_2` / `attachment_quartile_3`
Attachment completion	Attachment views reaching 100%.	Number	`attachment_view_completion`
Attachment total view time	Total attachment view time.	Duration	`attachment_total_view_time_millis`
Attachment average view time	Average attachment view time.	Duration	`attachment_avg_view_time_millis`

Conversions & installs

Metric	Description	Data type	API Key
Conversions	Attributed actions matching the defined conversion events. Defaults to purchases when no event is set.	Number	`conversion_purchases`
Conversion value	Monetary value of attributed conversions.	Currency	`conversion_purchases_value`
Revenue	Revenue rolled up from attributed conversions.	Currency	`conversion_purchases_value`
iOS installs	App installs attributed on iOS.	Number	`ios_installs`
Android installs	App installs attributed on Android.	Number	`android_installs`
Total installs	App installs across platforms.	Number	`total_installs`
Native leads	Lead-form submissions on Snapchat.	Number	`native_leads`

Custom conversion events

Conversion events tracked on the ad account are imported automatically and appear on the dashboard only when the underlying event is active. For each imported event, the connector also generates derived KPIs.

Metric	Description	Data type	API Key
[event]	Count of the tracked conversion event.	Number	`conversions:snapchat_reports:[event]`
[event]: Conversion value	Monetary value of the tracked event.	Currency	`conversionValue:snapchat_reports:[event]`
[event]: CVR	Conversion rate for the event.	Percentage	Adriel-computed (conversions / clicks × 100)
[event]: CPA	Cost per action for the event.	Currency	Adriel-computed (spend / conversions)
[event]: ROAS	Return on ad spend for the event.	Ratio	Adriel-computed (conversion value / spend)

Budget & schedule

Metric	Description	Data type	API Key
Budget	Budget set on the campaign or ad squad (daily or lifetime).	Currency	`lifetime_budget_micro`, `lifetime_spend_cap_micro`
Daily budget	Daily budget set on the campaign or ad squad.	Currency	`daily_budget_micro`
Lifetime budget	Total budget allocated for the campaign’s lifetime.	Currency	`lifetime_budget_micro`
Bid cap	Bid cap set on the campaign or ad squad.	Currency	`target_bid`
Bid strategy	Bid strategy set on the campaign or ad squad.	Text	`buy_model`, `bid_strategy`
Starts	Campaign / ad squad start date.	Date	`start_time`
Ends	Campaign / ad squad end date.	Date	`end_time`
Status	Campaign / ad squad / ad status.	Text	`status`, `delivery_status`, `review_status`

Campaign structure metadata

Metric	Description	Data type	API Key
Ad account name	Name of the ad account.	Text	`name`
Campaign name	Campaign name.	Text	`name`
Ad set name	Ad squad (ad set) name.	Text	`name`
Ad name	Ad name.	Text	`name`
Objective	Campaign objective.	Text	`objective`
Creative type	Creative format of the ad.	Text	Resolved from creative metadata
Creative URL	Link to the creative asset.	URL	`medias.download_link`
Channel	Channel where the ad is published.	Text	Constant rollup label

UTM tracking

UTM values are parsed by Adriel from each ad’s configuration and landing URL, not returned by Snapchat.

Metric	Description	Data type	API Key
UTM Source	Parsed `utm_source` parameter.	Text	Adriel-parsed from landing URL
UTM Medium	Parsed `utm_medium` parameter.	Text	Adriel-parsed
UTM Campaign	Parsed `utm_campaign` parameter.	Text	Adriel-parsed
UTM Content	Parsed `utm_content` parameter.	Text	Adriel-parsed
UTM Term	Parsed `utm_term` parameter.	Text	Adriel-parsed

Breakdowns

Standard hierarchy

Breakdown	Description	API Key
Campaign	Group by campaign.	`campaign_id`
Ad squad	Group by ad squad (ad set).	`ad_squad_id`
Ad	Group by ad.	`ad_id`

Segmentation

Only one segmentation breakdown can be applied per query, and these breakdowns are available at the ad-account level. When a segmentation breakdown is active, some metrics are unavailable (see Limitations).

Breakdown	Description	API Key
Age	Audience age range.	`age`
Gender	Audience gender.	`gender`
Location	Region where the impression occurred.	`region`
Device target	Operating system (iOS or Android).	`os`
Country	Country of the impression.	`country`
DMA region	US designated market area.	`dma`

Time & date grouping

Snapchat returns daily records; Adriel aggregates them into these time views for reporting.

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 week, starting Monday.
Weekly (Start: Sun)	Split reports by week, starting Sunday.
Week Date Breakdown	Group by day of the week during which the impression occurred.
Week Number Breakdown (W#)	Split by week number in the year.
Monthly	Split reports by calendar month.
Quarterly	Split reports by calendar quarter.
Yearly	Split reports by calendar year.

Creative analysis

Adriel post-processes ad creatives to generate these breakdowns.

Breakdown	Description
Ad Copy	Groups ads that share the same ad copy.
Creative Image	Auto-clusters identical or visually similar creative images.
Color Clustering	Groups creative images by dominant visual color.
Emoji Analysis	Groups ads by emojis present in the ad copy.

UTM tracking

Adriel parses UTM values from each ad’s landing URL and exposes them as breakdowns for grouping.

Breakdown	Description
UTM Source	Group by parsed `utm_source`.
UTM Medium	Group by parsed `utm_medium`.
UTM Campaign	Group by parsed `utm_campaign`.
UTM Content	Group by parsed `utm_content`.
UTM Term	Group by parsed `utm_term`.

Overview & status

These grouping options are provided by Adriel for organizing and rolling up reports.

Breakdown	Description
Channel	Constant grouping label used for cross-connector rollup.
Platform	Group results by the platform where the ads were broadcast.
No Grouping	Do not break down; return one aggregated row.
Objective	Group by campaign objective.
Status	Group by campaign / ad squad / ad status.

Limitations

No ad-account report level — report requests at the ad-account level are served at the campaign level; ad-account rollups aggregate campaign rows.
One segmentation breakdown at a time — the Snapchat API accepts a single report_dimension value per query, so age, gender, location, device target, country, and DMA region cannot be combined.
Metrics unavailable with segmentation — when a segmentation breakdown is active, 14 metric fields are removed from the request because the API rejects them in that combination, including average and total view-time metrics, video_views_15s, earned_impressions, earned_reach, total_reach, play_time_millis, profile_clicks, native_leads, and conversion_subscribe / its value.
Uniqueness over long ranges — reach and other uniqueness-based metrics can be overvalued for date ranges longer than one day, because uniqueness is computed per snapshot.
Cache-only reporting — dashboards read from cached snapshots, not live Snapchat data; values are most reliable within the actively synced 30-day window.
No deleted-data exclusion — data for elements deleted on the platform is not available after deletion.

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Attribution windows

Metrics

Reach & impressions

Clicks & engagement

Cost & spend

Video performance

Attachment performance

Conversions & installs

Custom conversion events

Budget & schedule

Campaign structure metadata

UTM tracking

Breakdowns

Standard hierarchy

Segmentation

Time & date grouping

Creative analysis

UTM tracking

Overview & status

Limitations

API references

See also

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Attribution windows

​Metrics

​Reach & impressions

​Clicks & engagement

​Cost & spend

​Video performance

​Attachment performance

​Conversions & installs

​Custom conversion events

​Budget & schedule

​Campaign structure metadata

​UTM tracking

​Breakdowns

​Standard hierarchy

​Segmentation

​Time & date grouping

​Creative analysis

​UTM tracking

​Overview & status

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Attribution windows

Metrics

Reach & impressions

Clicks & engagement

Cost & spend

Video performance

Attachment performance

Conversions & installs

Custom conversion events

Budget & schedule

Campaign structure metadata

UTM tracking

Breakdowns

Standard hierarchy

Segmentation

Time & date grouping

Creative analysis

UTM tracking

Overview & status

Limitations

API references

See also