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

## Introduction

ChatGPT Ads is OpenAI's advertising platform for placing ads in ChatGPT. Advertisers create campaigns, ad groups, and ads in OpenAI Ads Manager, and the connector imports the resulting structure and daily performance data through the OpenAI Ads API.

As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration. Currency and timezone follow the ad account's settings.

To connect this data source, see [How to connect ChatGPT Ads to Adriel](https://docs.adriel.com/data-sources/a-f/chatgpt-ads/how-to-connect.md).

## Data refresh strategy

### Architecture data

Architecture covers the ad account, campaigns, ad groups, and ads, including their names, statuses, budgets, and schedules. It refreshes **twice daily, at 5:00 AM and 4:00 PM UTC**.

### Reports data

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

**Real-time.** Report data is fetched from ChatGPT Ads on demand when a dashboard loads, so the latest available values are visible. On top of that, a scheduled cache refresh keeps recent data consistent.

**Refresh schedule.** **8:00 AM and 8:00 PM UTC daily** — syncs the last **3 days** for ad account, campaign, ad set, and ad.

On the ChatGPT Ads side, impressions and clicks can become available within minutes, spend reflects finalized activity and can update later than impressions and clicks, and conversions update through daily processing. OpenAI recommends allowing at least one day for conversion data to appear ([OpenAI Ads reporting](https://developers.openai.com/ads/reporting)). Recent days can therefore still change after they first load.

## Architecture levels

Ad account → Campaign → Ad set → Ad

ChatGPT Ads calls the ad set level an **ad group**. Ad group fields appear under ad set names in Adriel, such as **Ad Set Name** and **Ad Set ID**.

## Date range limits

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

## Attribution windows

Conversion metrics depend on the attribution settings chosen when the data source is connected:

* **Click attribution windows** — 7, 14, or 30 days after an ad click. Any combination can be selected; the default is 30 days. ChatGPT Ads supports these three click windows ([OpenAI Ads reporting](https://developers.openai.com/ads/reporting)).
* **Attribution time basis** — **Ad event time** dates a conversion on the day of the ad click or impression that received credit for it. **Conversion time** dates it on the day the conversion happened ([OpenAI Help Center](https://help.openai.com/en/articles/20001214-measure-results)). Either or both can be selected; the default is Ad event time.
* **View-through window** — fixed at **1 day** for every setting in Adriel. ChatGPT Ads itself supports a view-through window of 0 days (view-through disabled) or 1 day ([OpenAI Ads reporting](https://developers.openai.com/ads/reporting)).

The standard **Conversions** and **Conversion Value** metrics use the widest selected click window with a 1-day view window on an ad-event-time basis. With the default settings, that is 30-day click, 1-day view, ad event time.

In addition, each selected combination of click window and time basis gets its own conversion metric, named after the setting, plus four metrics derived from it. For example, a data source with a 30-day click window and both time bases includes:

| Metric | What it reports |
| - | - |
| ChatGPT Ads: Conversions Click 30d View 1d | Conversions for 30-day click and 1-day view, dated by ad event time. |
| ChatGPT Ads: Conversions Click 30d View 1d Conversion Time | Conversions for the same windows, dated by conversion time. |
| ChatGPT Ads: Conversions Click 30d View 1d: Conversion Value | Attributed conversion value for that setting. |
| ChatGPT Ads: Conversions Click 30d View 1d: CVR | Conversion rate for that setting, computed by Adriel. |
| ChatGPT Ads: Conversions Click 30d View 1d: CPA | Cost per conversion for that setting, computed by Adriel. |
| ChatGPT Ads: Conversions Click 30d View 1d: ROAS | Return on ad spend for that setting, computed by Adriel. |

The **Conversion Time** setting gets the same four derived metrics. Other click windows follow the same pattern, for example **Conversions Click 7d View 1d**.

## Metrics

> [!NOTE]
>
> **How to read the columns**
>
> **Data type** uses Adriel's vocabulary — Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. **API Key** in code style like `impressions` is the literal OpenAI Ads API field. Where the same raw field name is shared across objects (the API returns `name` and `id` for the ad account, campaign, ad group, and ad), it's shown qualified as `object.field` (for example `ad_group.name`) so each row stays unique. *Italic* marks a value Adriel computes or derives. Some raw fields back several metrics — notably `clicks` and `spend` — so the same key can appear on multiple rows; that's the shared source field, not a duplicated entry. Currency values are reported in the ad account's currency.

### Campaign Attributes

| Metric | Description | Data type | API Key |
| - | - | - | - |
| Active Status | Whether the campaign, ad group, or ad is currently active. | Text | *Adriel-side* |
| Ad Account Name | Name of the ChatGPT Ads ad account. | Text | `ad_account.name` |
| Ad Name | Name of the ChatGPT Ads ad. | Text | `ad.name` |
| Ad Set Name | Name of the ChatGPT Ads ad group. | Text | `ad_group.name` |
| Ad Spend | Amount spent, in the ad account currency. Reflects finalized ad activity and may lag behind impressions and clicks. | Currency | `spend` |
| Bid Cap | Maximum bid amount configured for the campaign or ad group when bid caps are used. | Currency | *Adriel-side* |
| Bid Strategy | Bidding strategy configured on the ad group. | Text | `bidding_config.strategy` |
| Budget | Campaign budget: the lifetime spend limit when one is set, otherwise the daily spend limit. | Text | `budget.lifetime_spend_limit_micros`, `budget.daily_spend_limit_micros` |
| Campaign Name | Name of the ChatGPT Ads campaign. | Text | `campaign.name` |
| Creative Type | Creative format of the ad, such as chat\_card or product\_ad\_template. | Text | `creative.type` |
| Creative URL | Creative preview of the ad: title, body, image, and destination URL. | Text | `creative` |
| Daily Budget | Daily spend limit of the campaign, converted from micros to the account currency. | Currency | `budget.daily_spend_limit_micros` |
| Ends | End time configured on the ChatGPT Ads campaign when one is set. | Date | `end_time` |
| Landing URL | The destination URL people reach from the ad. | URL | *Adriel-side* |
| Lifetime Budget | Lifetime spend limit of the campaign, converted from micros to the account currency. | Currency | `budget.lifetime_spend_limit_micros` |
| Objective | Campaign objective reported by ChatGPT Ads. | Text | `objective` |
| Starts | Start time configured on the ChatGPT Ads campaign when one is set. | Date | `start_time` |
| Status (Text) | A human-readable label for the current delivery status. | Text | *Adriel-side* |
| Status (Toggle) | Delivery status of the campaign, ad group, or ad (active, paused, or archived), combined with the ad review status. | Text | `status` |

### Campaign Structure

| Metric | Description | Data type | API Key |
| - | - | - | - |
| Ad Account ID | Unique ChatGPT Ads ad account identifier. | Text | `ad_account.id` |
| Ad ID | Unique ChatGPT Ads ad identifier. | Text | `ad.id` |
| Ad Set ID | Unique ChatGPT Ads ad group identifier. | Text | `ad_group.id` |
| Campaign ID | Unique ChatGPT Ads campaign identifier. | Text | `campaign.id` |
| Channel | Marketing sub-channels of the element. | Text | *Adriel-side* |

### Click Performance

| Metric | Description | Data type | API Key |
| - | - | - | - |
| Clicks (All) | Number of ad clicks recorded by ChatGPT Ads. | Number | `clicks` |
| CPC | Cost per click — spend divided by clicks. | Currency | *Adriel-computed* |
| CPM | Cost per thousand impressions. | Currency | *Adriel-computed* |
| CTR | Click-through rate — clicks divided by impressions. | Percentage | *Adriel-computed* |
| Impressions | Number of ad impressions recorded by ChatGPT Ads. | Number | `impressions` |
| Link Clicks | Number of ad clicks recorded by ChatGPT Ads. | Number | `clicks` |

> [!NOTE]
>
> **Link Clicks and Clicks (All) show the same value.** Both read the same OpenAI field, `clicks`, which counts the ad clicks recorded ([OpenAI Ads reporting](https://developers.openai.com/ads/reporting)), so either metric can be used in widgets that combine ChatGPT Ads with other ad platforms.

### Conversion Performance

| Metric | Description | Data type | API Key |
| - | - | - | - |
| Conversion Value | Value of attributed order\_created events in the account currency, reported for the same attribution setting as the conversions metric. | Currency | `order_created_attributed_sales` |
| Conversions | Goal conversions attributed to the ads, reported for the widest selected click attribution window on ad event time (30-day click / 1-day view by default). | Number | `conversions` |
| Result Indicator | The metric used to represent the result for the campaign's objective. | Text | *Adriel-derived* |
| Results | Result summary reported for the campaign's configured objective. | Text | *Adriel-derived* |

> [!NOTE]
>
> The per-setting conversion metrics described in [Attribution windows](https://docs.adriel.com/data-sources/a-f/chatgpt-ads/data-reference.md#attribution-windows) are added to each data source based on its attribution settings, so they aren't listed in this table.

### Creative Attributes

| Metric | Description | Data type | API Key |
| - | - | - | - |
| Creative Image | A reference to the ad's creative image. | Text | *Adriel-side* |

### ChatGPT Ads-specific

> [!NOTE]
>
> These metrics exist only for ChatGPT Ads and aren't part of any cross-connector category. Every group above is a standard category shared with other connectors.

| Metric | Description | Data type | API Key |
| - | - | - | - |
| Ad Spend | Amount spent, in the ad account currency. Reflects finalized ad activity and may lag behind impressions and clicks. | Currency | `spend` |

## Breakdowns

### Campaign Structure

| Breakdown | Description | API Key |
| - | - | - |
| Ad | Group results by ad. | *Adriel-side* |
| Ad Account | Group results by ad account. | *Adriel-side* |
| Ad Name | Groups results by ad name. | *Adriel-side* |
| Ad Set | Group results by ad group. | *Adriel-side* |
| Ad Set Name | Groups results by ad set name. | *Adriel-side* |
| Campaign | Group results by campaign. | *Adriel-side* |
| Campaign Name | Groups results by campaign name. | *Adriel-side* |
| Channel | Group results by marketing channel. | *Adriel-side* |
| Platform | Groups results by advertising platform. | *Adriel-side* |
| Status (Toggle) | Groups results by the current delivery status of the campaign, ad group, or ad. | *Adriel-side* |

### Creatives

| Breakdown | Description | API Key |
| - | - | - |
| Ad Copy | Groups results by words extracted from the ad creative. | *Adriel-side* |
| Color Clustering | Groups results by the dominant color cluster detected in the creative. | *Adriel-side* |
| Emoji Analysis | Groups results by emojis detected in the creative content. | *Adriel-side* |

### Date

> [!NOTE]
>
> ChatGPT Ads reports daily data. Weekly, monthly, and longer groupings are aggregated by Adriel from the daily rows, so they always add up to the daily totals.

| Breakdown | Description | API Key |
| - | - | - |
| Auto Time Breakdown | Use the connector default time grouping for the selected report. | *Adriel-side* |
| Daily Breakdown | Group results by day. | *Adriel-side* |
| Monthly Breakdown | Group results by month, aggregated from daily reporting. | *Adriel-side* |
| Quarterly Breakdown | Groups results by calendar quarter. | *Adriel-side* |
| Week Date Breakdown | Groups results by the date representing each reporting week. | *Adriel-side* |
| Week Number Breakdown (W#) | Groups results by week number in the year. | *Adriel-side* |
| Weekly Breakdown (Start: Mon) | Group results by week, aggregated from daily reporting. | *Adriel-side* |
| Weekly Breakdown (Start: Sun) | Groups results into weeks running from Sunday through Saturday. | *Adriel-side* |
| Yearly Breakdown | Groups results by calendar year. | *Adriel-side* |

### Others

| Breakdown | Description | API Key |
| - | - | - |
| No Grouping | Return totals without applying a report breakdown. | *Adriel-side* |

### Target

| Breakdown | Description | API Key |
| - | - | - |
| Country | Break down delivery results (impressions, clicks, spend) by country. Conversion metrics are not reported per country. | `country` |

> [!NOTE]
>
> **Country covers delivery metrics only.** Adriel's ChatGPT Ads data source does not import country-level conversions. With the Country breakdown, impressions, clicks, and spend are split by country, and conversion metrics stay empty. For conversion reporting, use a campaign structure or date breakdown.

## Limitations

* **365 days of history** — OpenAI serves non-hourly delivery reporting for the most recent 365 days ([OpenAI Ads reporting](https://developers.openai.com/ads/reporting)), so data older than that can't be imported.
* **Conversion Value from April 15, 2026** — Conversion Value and ROAS are available from April 15, 2026. Days before that date show no Conversion Value, while Conversions, spend, impressions, and clicks are not affected. On a date range that starts before April 15, 2026, ROAS reads lower than actual, because it uses spend for the full range but Conversion Value only from that date.
* **One ad account per data source** — each Ads API key is scoped to one ad account ([OpenAI Ads API authentication](https://developers.openai.com/ads/api-reference/authentication)). Connecting several ad accounts takes one key, and one data source, for each.
* **View-through window fixed at 1 day** — Adriel reports every attribution setting with a 1-day view window. A 0-day view window (click-through only) can't be selected.
* **No country-level conversions** — the Country breakdown returns delivery metrics only; see the note under [Target](https://docs.adriel.com/data-sources/a-f/chatgpt-ads/data-reference.md#target).

## API references (OpenAI)

* [OpenAI Ads API quickstart](https://developers.openai.com/ads/api-quickstart)
* [Authentication](https://developers.openai.com/ads/api-reference/authentication)
* [Reporting and attribution](https://developers.openai.com/ads/reporting)
* [Insights reference](https://developers.openai.com/ads/api-reference/insights)
* [Conversion tracking](https://developers.openai.com/ads/conversion-tracking)
* [Measure Results (OpenAI Help Center)](https://help.openai.com/en/articles/20001214-measure-results)

## See also

* [How to connect ChatGPT Ads to Adriel](https://docs.adriel.com/data-sources/a-f/chatgpt-ads/how-to-connect.md) (paired how-to)
* [ChatGPT Ads FAQs](https://docs.adriel.com/data-sources/a-f/chatgpt-ads/faqs.md) — expected behaviors and common questions
* [ChatGPT Ads release notes](https://docs.adriel.com/data-sources/a-f/chatgpt-ads/release-notes.md) — metric and behavior changes
* [StackAdapt data reference](https://docs.adriel.com/data-sources/o-z/stackadapt/data-reference.md) — for ChatGPT Ads bought through StackAdapt


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.