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

## Introduction

Adform is a global independent advertising technology platform offering DSP, ad serving, and audience tools for display, video, and rich media campaigns. The connector pulls campaign performance from the Adform Buyer Stats API, with breakdowns and metrics discovered dynamically from Adform's metadata endpoints so the available field set always reflects the current API surface.

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 Adform to Adriel](/data-sources/a-f/adform/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers advertisers, campaigns, line items or orders, and creatives. It is discovered dynamically through Adform's stats metadata APIs at data source creation and refreshed alongside reports.

### Reports data

Reports include daily performance for advertisers, campaigns, line items, and creatives.

**Simple cache.** Report data is fetched once per day and the cache is fully refreshed. Dashboards read from this cache rather than querying Adform on demand.

**Refresh schedule.** Reports refresh once daily at **1:00 AM UTC**. Each refresh pulls a fixed **397-day** historical window in a single request; because date is not driven by the dashboard, the entire window is always re-fetched.

## Architecture levels

Advertiser → Campaign → Line item / Order → Creative (Banner / Adgroup)

## Date range limits

The Adform connector always operates over a fixed **397-day** historical window. Queries that span dates outside this window return no data for the missing range, and the dashboard date range does not change the window that is fetched.

## 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 `campaign` is the literal Adform API field name. *Italic text* describes how a value is produced when it does not map cleanly to a single documented field — including standard Adform metrics, which are discovered dynamically from Adform's metadata endpoint rather than exposed under a stable documented key.
</Note>

Metrics are discovered dynamically from Adform's `v1/buyer/stats/metadata/metrics` endpoint at data source creation, so the available set reflects what the connected Adform account exposes. Metrics with sub-specifications are expanded into compound entries of the form `{metricTitle}_{specTitle}_{valueTitle}`. The commonly used set includes:

### Reach & impressions

| Metric      | Description                          | Data type | API Key                 |
| ----------- | ------------------------------------ | --------- | ----------------------- |
| Impressions | Number of ad displays (tracked ads). | Number    | *Adform metadata field* |

### Click performance

| Metric | Description          | Data type  | API Key                                  |
| ------ | -------------------- | ---------- | ---------------------------------------- |
| Clicks | Number of ad clicks. | Number     | *Adform metadata field*                  |
| CTR    | Click-through rate.  | Percentage | *Adriel-computed (clicks / impressions)* |

### Cost & spend

<Note>
  Spend and revenue are reported in the currency configured on the connected Adform account.
</Note>

| Metric         | Description                             | Data type | API Key                                       |
| -------------- | --------------------------------------- | --------- | --------------------------------------------- |
| Cost           | Reported network cost.                  | Currency  | *Adform metadata field*                       |
| CPC            | Cost per click.                         | Currency  | *Adriel-computed (cost / clicks)*             |
| CPM            | Cost per thousand impressions.          | Currency  | *Adriel-computed (cost / impressions × 1000)* |
| RTB media cost | Real-time-bidding media cost component. | Currency  | *Adform metadata field*                       |

### Engagement

| Metric | Description                                 | Data type | API Key                 |
| ------ | ------------------------------------------- | --------- | ----------------------- |
| Visits | Site visits attributed via Adform tracking. | Number    | *Adform metadata field* |

### Video performance

| Metric            | Description                      | Data type | API Key                 |
| ----------------- | -------------------------------- | --------- | ----------------------- |
| Video completions | Number of completed video plays. | Number    | *Adform metadata field* |

### Conversion performance

| Metric                | Description                          | Data type | API Key                 |
| --------------------- | ------------------------------------ | --------- | ----------------------- |
| Conversions (all)     | Attributed conversion events.        | Number    | *Adform metadata field* |
| Delivered conversions | Conversions delivered against goals. | Number    | *Adform metadata field* |
| Sales (all)           | Monetary value of conversions.       | Currency  | *Adform metadata field* |

## Breakdowns

Breakdowns are discovered dynamically from Adform's `v1/buyer/stats/metadata/dimensions` endpoint, with a maximum of 8 selected per data source.

### Campaign structure

| Breakdown        | Description                                      | API Key         |
| ---------------- | ------------------------------------------------ | --------------- |
| Campaign         | Group by Adform campaign.                        | `campaign`      |
| Line item        | Group by line item or order.                     | `lineItem`      |
| Order            | Group by order.                                  | `order`         |
| Banner / Adgroup | Group by banner or ad group (creative grouping). | `bannerAdgroup` |

### Creative

| Breakdown   | Description             | API Key      |
| ----------- | ----------------------- | ------------ |
| Banner size | Group by creative size. | `bannerSize` |
| Banner type | Group by creative type. | `bannerType` |

### Device & browser

| Breakdown    | Description            | API Key       |
| ------------ | ---------------------- | ------------- |
| Device type  | Group by device type.  | `deviceType`  |
| Device model | Group by device model. | `deviceModel` |
| Browser      | Group by browser.      | `browser`     |

### Audience

| Breakdown         | Description                    | API Key      |
| ----------------- | ------------------------------ | ------------ |
| DMP segment (DSP) | Group by DMP audience segment. | `dmpSegment` |

### Placement

| Breakdown  | Description                                  | API Key     |
| ---------- | -------------------------------------------- | ----------- |
| RTB domain | Group by real-time-bidding placement domain. | `rtbDomain` |

### Time

| Breakdown       | Description           | API Key |
| --------------- | --------------------- | ------- |
| Daily breakdown | Split reports by day. | `date`  |

## Limitations

* **Hard 8 breakdown / 10 metric cap** — Adform's Stats API enforces a maximum of 8 breakdowns and 10 metrics per data source ([Adform Reporting Stats API](https://api.adform.com/help/references/buyer-solutions/reporting/stats)). Selecting more raises an error and the data source is not created. To report on a wider field set, create multiple data sources.
* **Some breakdowns and metrics are blocked** — a subset of breakdowns and metrics is excluded because their compatibility with other fields cannot be reliably determined. Picking a blocked breakdown surfaces a "breakdown not available" error; picking a blocked metric surfaces a "metrics not available" error. Certain breakdown selections also dynamically exclude incompatible metrics from the picker before submission.
* **Fixed 397-day window** — each fetch always pulls a 397-day history, and the report query is not influenced by the dashboard date range ([Adform Reporting Stats API](https://api.adform.com/help/references/buyer-solutions/reporting/stats)). Data outside this window is not available.
* **Deleted elements are not provided** — once an element is removed from Adform, it is no longer returned by the connector.
* **Reports are generated asynchronously** — very large report requests may take time to build before data is available.

## API references

* [Adform API documentation](https://api.adform.com/)

## See also

* [How to connect Adform to Adriel](/data-sources/a-f/adform/how-to-connect) (paired how-to)
* [Adform FAQs](/data-sources/a-f/adform/faqs) — common questions about Adform data source behavior