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

## Introduction

StackAdapt is a multi-channel programmatic advertising platform (DSP) supporting native, display, video, audio, and CTV inventory across the open web. The connector pulls campaign architecture and performance from StackAdapt's GraphQL API for the advertisers selected during connection setup.

As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration.

<Note>
  New connections use the StackAdapt GraphQL variant documented here. The legacy StackAdapt REST connector is deprecated; existing REST widgets continue to function but appear with a "(deprecated)" suffix in the connector picker.
</Note>

To connect this data source, see [How to connect StackAdapt to Adriel](/data-sources/o-z/stackadapt/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers advertisers, campaigns, ad groups, and creatives. It refreshes twice daily at **4:00 PM UTC** and **5:00 AM UTC**.

### Reports data

Reports include daily performance for advertisers, campaigns, ad groups, and creatives.

**Real-time.** Report data is fetched from StackAdapt's GraphQL API 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

Advertiser → Campaign → Ad group → Creative

## Date range limits

| Breakdown | Max range |
| --------- | --------- |
| Daily     | 93 days   |
| Weekly    | 1 year    |

Data requested outside a breakdown's maximum range may be truncated. Longer historical ranges remain available through the monthly, quarterly, and yearly breakdowns.

## 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 `metrics.impressions` is the literal StackAdapt GraphQL response field. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

### Delivery & cost

| Metric      | Description                                                              | Data type  | API Key                                         |
| ----------- | ------------------------------------------------------------------------ | ---------- | ----------------------------------------------- |
| Impressions | Total times the ads were displayed.                                      | Number     | `metrics.impressions`                           |
| Clicks      | Total clicks, including link, social, and other interactions.            | Number     | `metrics.clicks`                                |
| Reach       | Unique users who saw the ad at least once.                               | Number     | `metrics.uniqueImpressions`                     |
| Ad spend    | Total amount spent during the reporting period (reported network spend). | Currency   | `metrics.cost`                                  |
| 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 × 1,000)* |

### Engagement

| Metric      | Description                                                                                                          | Data type | API Key               |
| ----------- | -------------------------------------------------------------------------------------------------------------------- | --------- | --------------------- |
| Engagements | Any user interaction with the ad, such as clicks, reactions, and shares (interactions on native and rich-media ads). | Number    | `metrics.engagements` |

### Video performance

| Metric                | Description                                    | Data type  | API Key                                             |
| --------------------- | ---------------------------------------------- | ---------- | --------------------------------------------------- |
| Video plays           | Any play of the video, regardless of duration. | Number     | `metrics.viewedMeasuredImpressions`                 |
| Views                 | Aggregated count of all qualified video views. | Number     | `metrics.videoStarts`                               |
| Video played to 25%   | Plays reaching 25% of video length.            | Number     | `metrics.videoQ1Playbacks`                          |
| Video played to 50%   | Plays reaching 50% of video length.            | Number     | `metrics.videoQ2Playbacks`                          |
| Video played to 75%   | Plays reaching 75% of video length.            | Number     | `metrics.videoQ3Playbacks`                          |
| Video completions     | Plays reaching 100% of video length.           | Number     | `metrics.videoCompletions`                          |
| Video completion rate | Share of video plays that reached 100%.        | Percentage | `metrics.videoCompletionRate`                       |
| VTR                   | View-through rate.                             | Percentage | *Adriel-computed (video completions / impressions)* |

### Conversion performance

| Metric           | Description                                                | Data type | API Key                                        |
| ---------------- | ---------------------------------------------------------- | --------- | ---------------------------------------------- |
| Conversions      | Attributed actions matching the defined conversion events. | Number    | `metrics.conversions`                          |
| Conversion value | Monetary value of attributed conversions.                  | Currency  | `metrics.revenue`, `metrics.conversionRevenue` |
| Revenue          | Revenue rolled up from attributed conversions.             | Currency  | `metrics.revenue`, `metrics.conversionRevenue` |

### Custom conversion events

For each conversion goal tracked by the StackAdapt pixel, a count metric and two derived efficiency metrics are generated.

| Pattern                  | Description                                               | Data type  | API Key                                           |
| ------------------------ | --------------------------------------------------------- | ---------- | ------------------------------------------------- |
| `[conversion_name]`      | Number of conversions tracked by the pixel for that goal. | Number     | `conversions:stackAdaptGraphQl:[conversion_name]` |
| `[conversion_name]: CVR` | Conversion rate for that goal.                            | Percentage | *Adriel-computed (conversions / clicks × 100)*    |
| `[conversion_name]: CPA` | Cost per action for that goal.                            | Currency   | *Adriel-computed (spend / conversions)*           |

### Budget & schedule

| Metric       | Description                                     | Data type | API Key                        |
| ------------ | ----------------------------------------------- | --------- | ------------------------------ |
| Budget       | Budget set on the campaign (daily or lifetime). | Currency  | `flights.nodes.lifetimeBudget` |
| Daily budget | Daily budget set on the campaign or ad group.   | Currency  | `flights.nodes.dailyBudget`    |
| Starts       | Campaign / flight start date.                   | Date      | `flights.nodes.startTime`      |
| Ends         | Campaign / flight end date.                     | Date      | `flights.nodes.endTime`        |

### Campaign structure metadata

| Metric          | Description                                                             | Data type | API Key                                                                   |
| --------------- | ----------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------- |
| Ad account name | Name of the advertiser (ad account).                                    | Text      | `name`                                                                    |
| Campaign name   | Campaign name.                                                          | Text      | `name`                                                                    |
| Ad set name     | Ad group name.                                                          | Text      | `name`                                                                    |
| Ad name         | Creative / ad name.                                                     | Text      | `name`                                                                    |
| Channel         | Channel where the ad is published (native, display, video, audio, CTV). | Text      | *Resolved from campaign metadata*                                         |
| Status          | Campaign / ad group / ad status.                                        | Text      | `campaignGroupStatus.status`, `campaignStatus.status`, `creativeStatus`   |
| Creative URL    | Creative asset URL.                                                     | URL       | `creativesConnection.nodes.s3Url`, `creativesConnection.nodes.thumbS3Url` |

## Breakdowns

### Standard hierarchy

| Breakdown  | Description                       | API Key      |
| ---------- | --------------------------------- | ------------ |
| Ad account | Group by advertiser (ad account). | `advertiser` |
| Campaign   | Group by campaign.                | `campaign`   |
| Ad set     | Group by ad group.                | `adGroup`    |
| Ad         | Group by creative (ad).           | `creative`   |

### Segmentation

| Breakdown | Description                                             | API Key   |
| --------- | ------------------------------------------------------- | --------- |
| Channel   | Group by channel (native, display, video, audio, CTV).  | `channel` |
| Country   | Group by impression location (two-letter country code). | `country` |
| Device    | Group by device type.                                   | `device`  |

### Time & date grouping

<Note>
  StackAdapt returns daily records; Adriel groups them into these 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 the day of the week on 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.          |
| Color Clustering | Groups creative images by dominant visual color. |
| Emoji Analysis   | Groups ads by emojis present in the ad copy.     |
| Creative Image   | Auto-clusters visually similar creative images.  |

### Overview & status

<Note>
  These groupings are provided by Adriel for organizing and rolling up report rows.
</Note>

| Breakdown   | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| No Grouping | Do not break down; return one aggregated row.                  |
| Objective   | Group by campaign objective.                                   |
| Status      | Group by campaign / ad group / ad status.                      |
| Platform    | Group results by the platform on which the ads were broadcast. |

## Limitations

* **GraphQL credentials are separate from REST** — a StackAdapt REST key will not authenticate against the GraphQL endpoint. GraphQL access must be requested directly from StackAdapt support.
* **Static API key, no rotation** — the key is not rotated automatically. If StackAdapt revokes the key on their side, the connection must be re-established with a fresh key.
* **One advertiser per data source** — when a single API key grants access to multiple advertisers, each selected advertiser creates its own data source. Cross-advertiser rollups happen at the dashboard layer.
* **Currency defaults to USD** — StackAdapt does not always provide currency metadata; when it is absent, USD is used as the default. Spend totals should be reviewed when working with non-USD advertisers.
* **Legacy REST connector deprecated** — the older StackAdapt REST connector is deprecated in favor of the GraphQL variant; new connections should use the GraphQL connector documented here.

## API references

* StackAdapt GraphQL API endpoint: `https://api.stackadapt.com/graphql`
* [StackAdapt developer documentation](https://docs.stackadapt.com/)

## See also

* [How to connect StackAdapt to Adriel](/data-sources/o-z/stackadapt/how-to-connect) (paired how-to)
* [The Trade Desk data reference](/data-sources/o-z/the-trade-desk/data-reference) — sibling DSP for programmatic media