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

## Introduction

Yahoo Ads is Yahoo's US and global advertising platform, delivering search, native, and display ads across Yahoo properties (Yahoo Mail, Yahoo Finance, Yahoo News, AOL) and partner publishers through the Gemini ad network. It is used by marketers reaching audiences outside the Google and Meta ecosystems, with CPC and CPM payment models across awareness, traffic, and conversion objectives. The connector authenticates with Yahoo's OAuth 2.0 flow and imports architecture and performance data through the Adriel backend rather than calling the Gemini API directly.

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

<Note>
  **Yahoo Ads vs Yahoo Japan vs Yahoo DSP**

  Three separate connector families share the Yahoo name. Yahoo Ads (this connector) covers Yahoo's US/global Gemini network. Yahoo Japan Search Ads and Yahoo Japan Display Ads cover the Japanese market with different APIs and breakdowns. Yahoo DSP covers programmatic display, video, native, CTV, and DOOH inventory through a different authentication flow.
</Note>

To connect this data source, see [How to connect Yahoo Ads to Adriel](/data-sources/o-z/yahoo-ads/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers ad accounts, campaigns, ad sets (ad groups), ads, and keywords. 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 the Gemini network on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled cache refreshes backfill late-arriving conversion and click data across several 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 group) → Ad → Keyword

Reports can be grouped at the campaign, ad set, ad, and keyword levels. The ad account level is used for architecture and account-wide totals but is not available as a report breakdown level.

## Date range limits

To keep query sizes manageable, the connector enforces these maximum look-back windows:

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

## Metrics

<Note>
  **How to read the columns**

  The **Data type** column shows how each value is formatted. In the **API Key** column, code style like `spend` is the literal Gemini reporting field, while *italic text* describes how a value is produced when it does not map to a single source field (for example Adriel-computed rates).
</Note>

### Reach & impressions

| Metric      | Description                             | Data type | API Key       |
| ----------- | --------------------------------------- | --------- | ------------- |
| Impressions | Number of times the ads were displayed. | Number    | `impressions` |

### Click performance

| Metric | Description                                | Data type  | API Key           |
| ------ | ------------------------------------------ | ---------- | ----------------- |
| Clicks | Number of clicks on the ads.               | Number     | `clicks`          |
| CTR    | Click-through rate (clicks ÷ impressions). | Percentage | *Adriel-computed* |

### Cost & spend

| Metric   | Description                                                                 | Data type | API Key           |
| -------- | --------------------------------------------------------------------------- | --------- | ----------------- |
| Ad spend | Total amount spent during the reporting period, in the ad account currency. | Currency  | `spend`           |
| CPC      | Average cost per click (spend ÷ clicks).                                    | Currency  | *Adriel-computed* |
| CPM      | Cost per thousand impressions (spend ÷ impressions × 1,000).                | Currency  | *Adriel-computed* |

<Note>
  **Currency conversion**

  Each ad account's currency is inherited from its Yahoo Ads settings. When an ad account's currency differs from the workspace currency, costs are automatically converted using the current day's exchange rate.
</Note>

### Conversion performance

| Metric           | Description                                                 | Data type | API Key            |
| ---------------- | ----------------------------------------------------------- | --------- | ------------------ |
| Conversions      | Attributed conversion events recorded by the Yahoo Dot tag. | Number    | `conversions`      |
| Conversion value | Monetary value attributed to conversions.                   | Currency  | `conversion_value` |

## Breakdowns

### Standard hierarchy

| Breakdown | Description                               | API Key    |
| --------- | ----------------------------------------- | ---------- |
| Campaign  | Group by campaign.                        | `campaign` |
| Ad set    | Group by ad set (ad group).               | `adSet`    |
| Ad        | Group by ad.                              | `ad`       |
| Keyword   | Group by keyword (search campaigns only). | `keyword`  |

### Demographics

| Breakdown | Description                      | API Key  |
| --------- | -------------------------------- | -------- |
| Gender    | Audience gender segmentation.    | `gender` |
| Age       | Audience age-range segmentation. | `age`    |

### Geographic

| Breakdown | Description                       | API Key    |
| --------- | --------------------------------- | ---------- |
| Location  | Geographic location segmentation. | `location` |

### Device

| Breakdown | Description                                       | API Key        |
| --------- | ------------------------------------------------- | -------------- |
| Device    | Device class, such as mobile, desktop, or tablet. | `deviceTarget` |

### Time & date grouping

<Note>
  Yahoo returns daily records; Adriel groups them into these views for reporting.
</Note>

| Breakdown | Description                      |
| --------- | -------------------------------- |
| Daily     | Split reports by day.            |
| Weekly    | Split reports by week.           |
| Monthly   | Split reports by calendar month. |

## Limitations

Based on the current connector, Yahoo Ads has the following limits:

* **Date-range caps** — daily breakdowns are limited to 93 days, weekly to 1 year, and monthly to 2 years. Data outside a selected breakdown's window may be truncated.
* **No ad-account-level breakdown** — reports can be grouped at the campaign, ad set, ad, and keyword levels only. The ad account level is not available as a report breakdown.
* **Search-only keyword data** — the Keyword breakdown returns data for search campaigns only.
* **Separate Yahoo connectors** — Yahoo Japan (Search and Display) and Yahoo DSP are distinct connectors with their own APIs, breakdowns, and refresh schedules. Data does not carry over between them.

## API references

* [Yahoo Ads (Gemini) API documentation](https://developer.yahooinc.com/)
* [Yahoo OAuth 2.0 overview](https://developer.yahooinc.com/oauth/)

## See also

* [Yahoo Ads how-to (paired)](/data-sources/o-z/yahoo-ads/how-to-connect) — step-by-step setup guide
* [Yahoo DSP data reference](/data-sources/o-z/yahoo-dsp/data-reference) — for programmatic display, video, native, CTV, and DOOH
* Yahoo Japan Search Ads data reference — for Japan-specific search advertising
* Yahoo Japan Display Ads data reference — for Japan-specific display advertising