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

## Introduction

Reddit Ads is Reddit's advertising platform, delivering promoted posts, video ads, and conversation placements across Reddit's interest-based communities. It is used by performance and brand marketers to reach audiences segmented by subreddit, interest, and demographic targeting, with CPC, CPM, and CPV payment models across awareness, traffic, and conversion objectives.

As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration. The connector covers paid campaigns only; for organic subreddit and post analytics, use the separate Reddit Public connector.

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

## Data refresh strategy

### Architecture data

Architecture covers ad accounts, campaigns, ad groups (ad sets), and ads. It refreshes twice daily at **4:00 PM UTC** and **5:00 AM UTC**. On data source creation, the cache fills with **362 days** of historical data for the ad account, campaign, ad set, and ad levels.

### Reports data

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

**Cache-only.** Report data comes from cached daily performance snapshots. Dashboard queries always read from the last snapshot, never live from Reddit, so very recent changes in Reddit Ads Manager appear only after the next scheduled sync.

**Refresh schedule.** Reports refresh **every 3 hours at minute 0 UTC**, syncing the last **90 days** for:

* Ad account, campaign, ad set, and ad
* Country, OS, platform placement, gender, and region (each per ad account)

Data is reliable within the 90-day cache sync window. Data outside this range may be incomplete or inaccurate due to legacy caching behavior.

## Architecture levels

Ad account → Campaign → Ad group (ad set) → Ad

## Date range limits

Reddit Ads reports are available at **daily granularity only**; weekly and monthly report breakdowns are not offered. The maximum lookback is approximately **363 days**, in line with Reddit's 12-month API restriction. Requests for data older than this window return a from-date-too-old error. Data within the last **90 days** is kept current by the scheduled cache refresh and is the most reliable; values outside that window may be incomplete.

## Metrics

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

  The **API Key** column shows where each value comes from. Code style like `impressions` is the literal Reddit Ads API field. *Italic text* describes a value Adriel computes on demand from other fields (for example, rates and cost ratios), because Reddit does not return it directly.
</Note>

### Delivery and cost

| Metric      | Description                                           | Data type  | API Key                                         |
| ----------- | ----------------------------------------------------- | ---------- | ----------------------------------------------- |
| Spend       | Reported spend, converted to the ad account currency. | Currency   | `spend`                                         |
| Impressions | Number of times ads were displayed.                   | Number     | `impressions`                                   |
| Clicks      | Number of clicks on ads.                              | Number     | `clicks`                                        |
| CTR         | Click-through rate.                                   | Percentage | *Adriel-computed (clicks ÷ impressions)*        |
| CPC         | Average cost per click.                               | Currency   | *Adriel-computed (spend ÷ clicks)*              |
| eCPM        | Effective cost per thousand impressions.              | Currency   | *Adriel-computed (spend ÷ impressions × 1,000)* |

<Note>
  Rate and average metrics such as CTR, CPC, and eCPM cannot be aggregated by Reddit's reporting API, so Adriel computes them on demand from the underlying spend, click, and impression totals.
</Note>

### Video

| Metric               | Description                                | Data type | API Key                     |
| -------------------- | ------------------------------------------ | --------- | --------------------------- |
| Video views          | Video plays that reached 10 seconds.       | Number    | `video_watched_10_seconds`  |
| 3-second video views | Video plays that reached 3 seconds.        | Number    | `video_watched_3_seconds`   |
| Video views at 25%   | Video plays that reached 25% of the video. | Number    | `video_watched_25_percent`  |
| Video views at 50%   | Video plays that reached 50% of the video. | Number    | `video_watched_50_percent`  |
| Video views at 75%   | Video plays that reached 75% of the video. | Number    | `video_watched_75_percent`  |
| Video completions    | Video plays that ran to 100%.              | Number    | `video_watched_100_percent` |

### Conversions and revenue

| Metric        | Description                                              | Data type | API Key                                              |
| ------------- | -------------------------------------------------------- | --------- | ---------------------------------------------------- |
| Pixel revenue | Revenue attributed to conversions from the Reddit Pixel. | Currency  | `conversion_purchase_total_value` *(divided by 100)* |

## Breakdowns

### Structure

| Breakdown | Description                 | API Key       |
| --------- | --------------------------- | ------------- |
| Campaign  | Group by campaign.          | `campaign_id` |
| Ad group  | Group by ad group (ad set). | `ad_group_id` |
| Ad        | Group by ad.                | `ad_id`       |

### Demographics and geography

| Breakdown | Description                | API Key   |
| --------- | -------------------------- | --------- |
| Country   | Country of the impression. | `country` |
| Region    | Sub-country region.        | `region`  |
| Gender    | Audience gender.           | `gender`  |

<Note>
  Demographic and geographic breakdowns are reported at the ad account level only and cannot be combined with campaign, ad set, or ad granularity in the same query.
</Note>

### Device and placement

| Breakdown          | Description                                                | API Key     |
| ------------------ | ---------------------------------------------------------- | ----------- |
| OS                 | Operating system, such as Android, iOS, macOS, or Windows. | `os`        |
| Platform placement | Placement surface, such as feed or comments page.          | `placement` |

<Note>
  Device and placement breakdowns are reported at the ad account level only and cannot be combined with campaign, ad set, or ad granularity in the same query.
</Note>

### Time

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

## Limitations

* **Cache-only reads.** Dashboards never query Reddit live for reports. All metric values come from the most recent cache snapshot, so recent changes inside Reddit Ads Manager appear only after the next scheduled sync.
* **Uniqueness over longer ranges.** Metrics based on uniqueness (such as reach) can be overvalued when viewed for a date period longer than one day, because uniqueness is computed per snapshot rather than across the full range.
* **Breakdowns scoped to ad account.** Demographic, geographic, device, and placement breakdowns (country, region, gender, OS, platform placement) are available at the ad account level only and cannot be combined with campaign, ad set, or ad granularity.
* **Daily reporting only.** Reports support day-level granularity only; weekly and monthly report breakdowns are not available.
* **Maximum lookback.** Reports cannot be queried beyond approximately 363 days, in line with Reddit's 12-month API restriction; older requests return a from-date-too-old error.
* **Reliable window.** Data older than the 90-day cache sync window may be incomplete, missing, or inaccurate due to legacy caching behavior.
* **Deleted elements.** Deleted campaigns, ad sets, and ads are not provided by the connector.
* **Non-aggregatable metrics.** Rate, average, and effective-cost metrics (such as CTR, CPC, CPV, eCPM, eCPC, and eCPA) cannot be requested directly from Reddit's reporting API; Adriel computes them on demand from raw totals.

## API references

* **Reddit Ads API v3** — base URL `ads-api.reddit.com/api/v3/`. Reports are fetched by POST to `ad_accounts/{id}/reports`.
* **Authentication** — OAuth 2.0 authorization code flow. After authorization, the refresh token is stored and access tokens are renewed automatically. Requested scopes: `adsread`, `history`, `identity`, `adsconversions`, `adsedit`.
* **Currency** — inherited from the connected Reddit ad account.
* **Rate limit** — Reddit enforces a maximum of one request per 12 seconds per ad account; global per-owner limits may also apply.

## See also

* [Reddit Public data reference](/data-sources/o-z/reddit-public/data-reference) — for public subreddit and post-level data.
* [How to connect Reddit to Adriel](/data-sources/o-z/reddit/how-to-connect)