> ## 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 Snapchat data source in Adriel.

## 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-sources/o-z/snapchat/how-to-connect).

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

<Note>
  **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.
</Note>

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

<Note>
  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.
</Note>

| 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

<Note>
  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.
</Note>

| 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

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

| 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

<Note>
  UTM values are parsed by Adriel from each ad's configuration and landing URL, not returned by Snapchat.
</Note>

| 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

<Note>
  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).
</Note>

| 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

<Note>
  Snapchat returns daily records; Adriel aggregates them into these time views for reporting.
</Note>

| 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

<Note>
  Adriel post-processes ad creatives to generate these breakdowns.
</Note>

| 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

<Note>
  Adriel parses UTM values from each ad's landing URL and exposes them as breakdowns for grouping.
</Note>

| 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

<Note>
  These grouping options are provided by Adriel for organizing and rolling up reports.
</Note>

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

## API references

* [Snapchat Marketing API](https://developers.snap.com/api/marketing-api/Ads-API/introduction)
* [Campaign, ad squad, and ad management](https://developers.snap.com/api/marketing-api/Ads-API/campaign-management/campaigns)
* [Reporting and stats](https://developers.snap.com/api/marketing-api/Ads-API/measurement/get-stats)

## See also

* [How to connect Snapchat to Adriel](/data-sources/o-z/snapchat/how-to-connect) (paired how-to)
* [TikTok Ads data reference](/data-sources/o-z/tiktok/data-reference) — for comparable short-video performance analysis