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

## Introduction

RTB House is a retargeting and programmatic advertising platform. The Adriel connector fetches campaign structure and performance data from the RTB House API (v5), including impressions, clicks, advertiser cost, and conversion metrics reported across multiple count conventions.

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 RTB House to Adriel](/data-sources/o-z/rtb-house/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers ad accounts, campaigns, ad sets, and ads. It refreshes twice daily, at **4:00 PM UTC** and **5:00 AM UTC**.

### Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad sets, and ads.

**Real-time.** Report data is fetched from RTB House 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

Ad account → Campaign → Ad set → Ad

<Note>
  RTB House campaigns and ad sets share the same underlying subcampaign endpoint, so ad sets are modeled from subcampaign data. Statuses are normalized to Adriel values: `ACTIVE` → running, `PAUSED` → paused, `NEW` → scheduled, `READY` → in review.
</Note>

## Date range limits

To keep query sizes manageable, the maximum look-back window depends on the date grouping:

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

## Attribution windows

RTB House reports conversions under four **count conventions**. After the base performance request, the connector issues one additional request per convention, and each convention produces its own conversion count and conversion value.

| Convention      | Meaning                                            | API value         |
| --------------- | -------------------------------------------------- | ----------------- |
| Attributed      | Conversions within the default attribution window. | `ATTRIBUTED`      |
| Post-view       | View-through conversions.                          | `POST_VIEW`       |
| All post-click  | All post-click conversions.                        | `ALL_POST_CLICK`  |
| All conversions | All conversion types combined.                     | `ALL_CONVERSIONS` |

Each convention generates a separate metric variant — for example, conversions are exposed as `conversions:rtbHouse:ATTRIBUTED`, `conversions:rtbHouse:POST_VIEW`, and so on, with a matching `conversionValue:rtbHouse:{convention}` for value.

## 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 `impsCount` is the literal RTB House API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

### Delivery & clicks

| Metric       | Description                                                          | Data type  | API Key                          |
| ------------ | -------------------------------------------------------------------- | ---------- | -------------------------------- |
| Impressions  | Total times the ads were shown.                                      | Number     | `impsCount`                      |
| Clicks       | Total clicks on the ads.                                             | Number     | `clicksCount`                    |
| Clicks (all) | Total clicks across all click types; mirrors Clicks for this source. | Number     | *Mapped from `clicksCount`*      |
| CTR          | Click-through rate.                                                  | Percentage | *Derived (clicks ÷ impressions)* |

### Cost & spend

<Note>
  Currency values are reported in the ad account's configured RTB House currency. If that differs from the workspace currency, costs are converted using the current day's exchange rate.
</Note>

| Metric   | Description                                | Data type | API Key                                |
| -------- | ------------------------------------------ | --------- | -------------------------------------- |
| Ad spend | Advertiser cost over the reporting period. | Currency  | `campaignCost`                         |
| CPM      | Cost per thousand impressions.             | Currency  | *Derived (spend ÷ impressions × 1000)* |
| CPC      | Cost per click.                            | Currency  | *Derived (spend ÷ clicks)*             |

### Conversions & value

<Note>
  Conversion metrics are reported per count convention (see [Attribution windows](#attribution-windows)). Each named conversion event also generates its own set of derived metrics.
</Note>

| Metric           | Description                                                                                   | Data type  | API Key                         |
| ---------------- | --------------------------------------------------------------------------------------------- | ---------- | ------------------------------- |
| Conversions      | Number of conversions recorded for the selected convention.                                   | Number     | `conversionsCount`              |
| Conversion value | Monetary value of attributed conversions.                                                     | Currency   | `conversionsValue`              |
| Conversion rate  | Conversion rate reported by RTB House for the selected convention.                            | Percentage | `cr`                            |
| eCPA             | Effective cost per acquisition for the selected convention.                                   | Currency   | `ecpa`                          |
| Revenue          | Monetary value of attributed conversions; defaults to Purchase when no specific event is set. | Currency   | *Derived from conversion value* |

**Per-conversion metrics.** For each named conversion, the following dynamic columns are generated (where `{convention}` is one of the four count conventions):

| Metric                                     | Description                                  | Data type  | API Key                                      |
| ------------------------------------------ | -------------------------------------------- | ---------- | -------------------------------------------- |
| RTB House: \[conversion]                   | Count of the named conversion.               | Number     | `conversions:rtbHouse:{convention}`          |
| RTB House: \[conversion]: Conversion value | Value of the named conversion.               | Currency   | `conversionValue:rtbHouse:{convention}`      |
| RTB House: \[conversion]: CVR              | Conversion rate for the named conversion.    | Percentage | *Derived (conversions ÷ clicks (all) × 100)* |
| RTB House: \[conversion]: CPA              | Cost per action for the named conversion.    | Currency   | *Derived (spend ÷ conversions)*              |
| RTB House: \[conversion]: ROAS             | Return on ad spend for the named conversion. | Ratio      | *Derived (conversion value ÷ spend)*         |

### 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 (subcampaign) name.                                       | Text      | `name`                            |
| Ad name         | Ad (creative) identifier.                                        | Text      | `hash`                            |
| Status          | Campaign, ad set, or ad status.                                  | Text      | `status`                          |
| Objective       | Campaign objective.                                              | Text      | *From campaign metadata*          |
| Budget          | Configured budget on the campaign or ad set (daily or lifetime). | Currency  | *From campaign / ad set metadata* |
| Daily budget    | Configured daily budget.                                         | Currency  | *From campaign / ad set metadata* |
| Lifetime budget | Configured lifetime budget.                                      | Currency  | *From campaign / ad set metadata* |
| Bid cap         | Bid cap set on the campaign or ad set.                           | Currency  | *From campaign / ad set metadata* |
| Bid strategy    | Bid strategy set on the campaign or ad set.                      | Text      | *From campaign / ad set metadata* |
| Starts          | Start date.                                                      | Date      | *From campaign / ad set metadata* |
| Ends            | End date.                                                        | Date      | *From campaign / ad set metadata* |
| Creative type   | Type of the creative.                                            | Text      | *From creative metadata*          |
| Creative URL    | URL of the creative.                                             | URL       | *From creative metadata*          |

## Breakdowns

### Campaign structure

| Breakdown  | Description                    | API Key |
| ---------- | ------------------------------ | ------- |
| Ad account | Group by ad account.           | `name`  |
| Campaign   | Group by campaign.             | `name`  |
| Ad set     | Group by ad set (subcampaign). | `name`  |
| Ad         | Group by ad (creative).        | `hash`  |

### Date breakdowns

| Breakdown           | Description                                 | API Key                             |
| ------------------- | ------------------------------------------- | ----------------------------------- |
| Daily               | Split reports by day.                       | `groupBy=day`                       |
| Weekly (Start: Mon) | Split reports by ISO week, starting Monday. | `groupBy=day` *(grouped by Adriel)* |
| Weekly (Start: Sun) | Split reports by week, starting Sunday.     | `groupBy=week`                      |
| Monthly             | Split reports by calendar month.            | `groupBy=month`                     |

### Overview

<Note>
  Adriel-provided grouping options that do not map to an RTB House field.
</Note>

| Breakdown   | Description                                     |
| ----------- | ----------------------------------------------- |
| No grouping | Do not break down; return one aggregated row.   |
| Channel     | Constant label used for cross-connector rollup. |

### Creative

<Note>
  Adriel post-processes ad creatives to group visually similar images together.
</Note>

| Breakdown      | Description                                            |
| -------------- | ------------------------------------------------------ |
| Creative image | Group reports by identical or similar creative images. |

## Limitations

* **365-day report window** — a single report query is capped at 365 days. Wider ranges are split into multiple requests.
* **Archived entities** — archived campaigns and ad sets are included in architecture, while archived ad accounts (advertisers) are excluded. Reports may therefore contain entities that are no longer actively managed.
* **Active creatives only at the ad level** — ad-level architecture is fetched with `activeOnly=true`, so paused or archived creatives may not appear as ads.
* **Ad-to-campaign resolution via cache** — at the ad level, each row's parent campaign is resolved from a 10-minute architecture cache. A creative not yet present in the cache may temporarily lack a campaign association.

## API references

The connector calls the RTB House API (v5) using HTTP Basic authentication. The endpoints used are:

* `GET /advertisers` — ad accounts
* `GET /advertisers/{hash}/campaigns` — campaigns and ad sets (subcampaigns)
* `GET /advertisers/{hash}/rtb-creatives` — ads (creatives)
* `GET /advertisers/{advertiserId}/rtb-stats` — report statistics at all levels

## See also

* [How to connect RTB House to Adriel](/data-sources/o-z/rtb-house/how-to-connect) (paired how-to)
* [Meta Ads data reference](/data-sources/g-n/meta-ads/data-reference) — for another ad-platform reference
* [Criteo data reference](/data-sources/a-f/criteo/data-reference) — for another retargeting / programmatic platform