> ## 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 Yahoo DSP data source in Adriel.
## Introduction
Yahoo DSP (Demand-Side Platform) is a programmatic advertising platform that lets advertisers buy and manage digital inventory across Yahoo's network and third-party publishers. The connector pulls campaign architecture and performance across display, video, native, connected TV (CTV), and digital out-of-home (DOOH) inventory.
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 Yahoo DSP to Adriel](/data-sources/o-z/yahoo-dsp/how-to-connect).
## Data refresh strategy
### Architecture data
Architecture covers ad accounts, campaigns, ad sets (line items), and ads (creatives). It refreshes twice daily at **4:00 PM UTC** and **5:00 AM UTC**. When the data source is created, the cache fills with **730 days** of historical architecture data for the ad account, campaign, ad set, and ad levels.
### Reports data
Reports include daily performance for ad accounts, campaigns, ad sets, and ads.
**Cache-only.** Report data comes from cached daily performance snapshots produced by an asynchronous report pipeline (create a report job, poll until it completes, download the resulting CSV). Live fetch is not supported, so every dashboard query reads the most recent cached snapshot.
**Refresh schedule.** Reports refresh **every 6 hours, at 0 minutes past the hour (UTC)**. Each refresh syncs the **last 10 days** for the ad account, campaign, ad set, and ad levels. Data is considered reliable within the cache sync period; data outside this range may be incomplete or not fully accurate due to legacy caching behavior.
Metrics based on uniqueness, such as reach and unique households, can be overstated when viewed across a date range longer than one day, because daily snapshot values are summed.
## Architecture levels
Yahoo DSP → Ad account → Campaign → Ad set (line item) → Ad (creative)
## Date range limits
| Breakdown | Max range |
| --------- | --------- |
| Daily | 93 days |
| Weekly | 1 year |
| Monthly | 2 years |
Data requested outside a breakdown's maximum range may be truncated. Longer historical ranges remain available through the quarterly and yearly breakdowns.
## 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 Yahoo DSP report column the connector maps. *Italic text* describes how a value is produced when it does not map cleanly to a single API field.
### Delivery & cost
| Metric | Description | Data type | API Key |
| ------------------------- | ----------------------------------------------------------- | ---------- | --------------------------- |
| Impressions | Number of times the ads were displayed. | Number | `Impressions` |
| Clicks | Total ad clicks. | Number | `Clicks` |
| Advertiser spending | Reported network spend for the advertiser. | Currency | `Advertiser Spending` |
| CTR | Click-through rate. | Percentage | `CTR` |
| CPC | Cost per click. | Currency | `CPC` |
| Advertiser eCPM | Effective cost per thousand impressions for the advertiser. | Currency | `Advertiser eCPM` |
| Inventory eCPM | Effective cost per thousand impressions for inventory. | Currency | `Inventory eCPM` |
| Network eCPM | Effective cost per thousand impressions across the network. | Currency | `Network eCPM` |
| VCPM | Cost per thousand viewable impressions. | Currency | `VCPM` |
| Estimated billable amount | Estimated amount billable for the reporting period. | Currency | `Estimated Billable Amount` |
### Viewability
| Metric | Description | Data type | API Key |
| -------------------------------- | ------------------------------------------------------------ | ---------- | ---------------------------------- |
| Yahoo viewable impressions | Impressions measured as viewable by Yahoo. | Number | `Yahoo Viewable Impressions` |
| Yahoo viewable rate | Share of measurable impressions that were viewable. | Percentage | `Yahoo Viewable Rate` |
| Yahoo measurable impressions | Impressions that could be measured for viewability. | Number | `Yahoo Measurable Impressions` |
| Yahoo measurable rate | Share of impressions that could be measured for viewability. | Percentage | `Yahoo Measurable Rate` |
| Moat viewable impressions | Viewable impressions measured by Moat. | Number | `Moat Viewable Impressions` |
| Moat viewable rate | Share of impressions measured as viewable by Moat. | Percentage | `Moat Viewable Rate` |
| Impression distribution viewable | Share of impressions distributed as viewable. | Percentage | `Impression Distribution Viewable` |
### Video performance
| Metric | Description | Data type | API Key |
| ------------------------------- | --------------------------------------------------- | ---------- | --------------------------------- |
| Start views | Aggregated count of qualified video views (starts). | Number | `Start Views` |
| Video played to 25% | Plays reaching 25% of video length. | Number | `25% Complete` |
| Video played to 50% | Plays reaching 50% of video length. | Number | `50% Complete` |
| Video played to 75% | Plays reaching 75% of video length. | Number | `75% Complete` |
| Video played to 100% | Plays reaching 100% of video length. | Number | `100% Complete` |
| 100% completion rate | Share of plays that reached 100% of video length. | Percentage | `100% Completion Rate` |
| CPCV | Cost per completed video view. | Currency | `CPCV` |
| Cost per valid video view (CPV) | Cost per valid video view. | Currency | `Cost Per Valid Video View (CPV)` |
| Companion impressions | Impressions on companion video creatives. | Number | `Companion Impressions` |
| Companion clicks | Clicks on companion video creatives. | Number | `Companion Clicks` |
| Skipped ads | Video ads skipped by the viewer. | Number | `Skipped Ads` |
### Conversion performance
| Metric | Description | Data type | API Key |
| ----------------------------- | ----------------------------------------------- | ---------- | ------------------------------- |
| Conversion | Attributed conversion events. | Number | `Conversion` |
| CNVR | Conversion rate. | Percentage | `CNVR` |
| Click-through conversion rate | Conversion rate from click-through conversions. | Percentage | `Click Through Conversion Rate` |
| View-through conversion rate | Conversion rate from view-through conversions. | Percentage | `View Through Conversion Rate` |
| Cross-device conversions | Conversions attributed across devices. | Number | `Cross-device Conversions` |
| Third-party conversions | Conversions reported by a third-party source. | Number | `Third Party Conversions` |
| Tracked actions | Tracked post-engagement actions (GAN access). | Number | `Tracked Actions` |
### Custom conversion events
Conversion events tracked in the ad account are imported automatically and appear on the dashboard only while the underlying event is active. For each imported conversion goal, the connector also generates derived efficiency metrics.
| Pattern | Description | Data type | API Key |
| ------------------------------------- | --------------------------------------------------------- | ---------- | ---------------------------------------------- |
| `[conversion_name]` | Number of conversions tracked by the pixel for that goal. | Number | *Dynamic per conversion goal* |
| `[conversion_name]: Conversion value` | Monetary value of conversions for that goal. | Currency | *Dynamic per conversion goal* |
| `[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)* |
| `[conversion_name]: ROAS` | Return on ad spend for that goal. | Ratio | *Adriel-computed (conversion value / spend)* |
### Audience & reach
| Metric | Description | Data type | API Key |
| ------------------------------- | --------------------------------------------------- | --------- | --------------------------------- |
| Unique households | Distinct households reached (CTV). | Number | `Unique Households` |
| Average frequency per household | Average impression frequency per household (CTV). | Ratio | `Average Frequency per Household` |
| Average people frequency | Average impression frequency per person. | Ratio | `Average People Frequency` |
| Audience impressions | Estimated people likely to notice a DOOH message. | Number | `Audience Impressions` |
| Average impression multiplier | Audience impressions divided by impressions (DOOH). | Ratio | `Average Impression Multiplier` |
### Fees & cost breakdown
| Metric | Description | Data type | API Key |
| ------------------------- | --------------------------------------------- | --------- | --------------------------- |
| Ad serving cost | Cost of serving the ads. | Currency | `Ad Serving Cost` |
| Ad verification cost | Cost of ad verification services. | Currency | `Ad Verification Cost` |
| Audience measurement cost | Cost of audience measurement services. | Currency | `Audience Measurement Cost` |
| Brand safety cost | Cost of brand-safety services. | Currency | `Brand Safety Cost` |
| Viewability cost | Cost of viewability measurement services. | Currency | `Viewability Cost` |
| Seat tech fee | Seat-level technology fee. | Currency | `Seat Tech Fee` |
| Seat data fee | Seat-level data fee. | Currency | `Seat Data Fee` |
| Seat management fee | Seat-level management fee. | Currency | `Seat Management Fee` |
| Order management fee | Order-level management fee. | Currency | `Order Management Fee` |
| Total variable cost | Total variable cost for the reporting period. | Currency | `Total Variable Cost` |
| Total vendor fee | Total third-party vendor fees. | Currency | `Total Vendor Fee` |
### 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 set (line item) name. | Text | `name` |
| Ad name | Ad (creative) name. | Text | `name` |
| Channel | Channel where the ad is published, such as display, video, native, CTV, or DOOH. | Text | *Resolved from campaign metadata* |
| Status | Campaign, ad set, or ad status. | Text | `status` |
| UTM parameters | UTM source, medium, campaign, content, and term, extracted from the ad settings or landing-page URL when present. | Text | *Parsed from ad settings and destination URL* |
## Breakdowns
### Standard hierarchy
| Breakdown | Description | API Key |
| ---------- | ------------------------------------------------------ | ------- |
| Ad account | Group by ad account (based on the ad account ID). | `name` |
| Campaign | Group by campaign (based on the campaign ID). | `name` |
| Ad set | Group by ad set or line item (based on the ad set ID). | `name` |
| Ad | Group by ad or creative (based on the ad ID). | `name` |
### Audience & segmentation
| Breakdown | Description | API Key |
| --------- | ----------------------------------------------------------------------------------------------------------- | --------------------- |
| Channel | Group by channel, such as display, video, native, CTV, or DOOH. | `channel` |
| Location | Split reports by impression location; depending on the platform, this can be countries, regions, or cities. | `country,region,city` |
| Device | Group by device type. | `device` |
| Age | Group reports by audience age range. | `age` |
| Gender | Group reports by audience gender. | `gender` |
| Objective | Group campaigns by their objective. | `goalType` |
| Status | Group by campaign, ad set, or ad status. | `status` |
### Time & date grouping
Yahoo DSP returns daily records; Adriel groups them into these views for reporting.
| Breakdown | Description |
| ----------------------------- | ---------------------------------------------------------------------- |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily breakdown | Split reports by day. |
| Weekly breakdown (Start: Mon) | Split reports by week, starting Monday. |
| Weekly breakdown (Start: Sun) | Split reports by week, starting Sunday. |
| Week Date Breakdown | Group results by the day of the week on which the impression occurred. |
| Week Number Breakdown (W#) | Split by week number within the year. |
| Monthly breakdown | Split reports by calendar month. |
| Quarterly breakdown | Split reports by calendar quarter. |
| Yearly breakdown | Split reports by calendar year. |
### Creative analysis
Adriel post-processes ad creatives to generate these breakdowns.
| Breakdown | Description |
| ---------------- | ----------------------------------------------------------- |
| Ad copy | Group ads that share the same ad copy. |
| Color Clustering | Group creative images by dominant visual color. |
| Emoji Analysis | Group ads by emojis present in the ad copy. |
| Creative image | Auto-cluster identical or visually similar creative images. |
### Rollups
These groupings are provided by Adriel for organizing and rolling up report rows.
| Breakdown | Description |
| ----------- | -------------------------------------------------------------- |
| No Grouping | Do not break down; return one aggregated row. |
| Platform | Group results by the platform on which the ads were broadcast. |
## Limitations
* **Cache-only reporting** — reports come from cached daily snapshots, not live fetch. Every dashboard query reads the most recent snapshot, and values outside the 10-day rolling sync window (within the 730-day backfill) may be incomplete or not fully accurate.
* **Uniqueness metrics can be overstated** — reach, unique households, and similar metrics are summed from daily snapshots, so multi-day ranges can overcount unique audiences.
* **No long-lived refresh token** — Yahoo DSP's JWT-bearer flow does not issue a refresh token. A fresh JWT is constructed and exchanged for a new access token (1-hour TTL) on demand whenever the current one expires. The exchange is invisible to dashboards.
* **Metric availability depends on access type** — Seat access exposes the full metric set, including video completion counts and rates, viewability (Yahoo and Moat), frequency, and seat fees. General Access Network (GAN) access is limited to core delivery, click, conversion, VCPM, CPCV, and tracked-action metrics.
* **Channel-specific metrics** — CTV metrics, such as unique households and average frequency per household, and DOOH metrics, such as audience impressions and average impression multiplier, appear only on those placement types; average frequency per household may be limited for EU audiences due to privacy restrictions. Yahoo Native mail-ad and tile metrics apply only to Yahoo Native placements under Seat access.
* **Date range caps per breakdown** — daily breakdowns are capped at 93 days, weekly at 1 year, and monthly at 2 years; longer ranges rely on quarterly and yearly breakdowns.
## API references
* Reports are retrieved through the Yahoo DSP `extreport` asynchronous reporting API (create a job, poll until it succeeds or fails, then download the CSV).
* Authentication uses Yahoo DSP's JWT-bearer OAuth2 client-credentials flow; a short-lived access token is passed in the `X-Auth-Token` header.
* [Yahoo DSP API documentation](https://developer.yahooinc.com/dsp/api/docs/)
## See also
* [How to connect Yahoo DSP to Adriel](/data-sources/o-z/yahoo-dsp/how-to-connect) (paired how-to)
* [Yahoo Ads data reference](/data-sources/o-z/yahoo-ads/data-reference) — for non-programmatic Yahoo advertising
* [Amazon DSP data reference](/data-sources/a-f/amazon-dsp/data-reference) — for a comparable programmatic DSP integration