ChatGPT Ads

Pull advertising data from the ChatGPT Ads platform including campaigns, ad groups, ads, and performance insights.

info

API Documentation: ChatGPT Ads API Overview | Authentication Reference

Overview

The chatgpt_ads connector lets you sync data between ChatGPT Ads and your workspace. It supports:

• Reporting (Insights): pull performance and delivery metrics from ChatGPT Ads.
• Audiences (Reverse ETL destination): push user identifiers to ChatGPT Custom Audiences to add or remove members.

Audience syncing is append-only and is designed to work from a full snapshot with diffing (recommended) or from an upstream process that provides an explicit per-row action. Each sync applies membership changes to a single ChatGPT audience list.

Setup Guide

To configure ChatGPT Ads as a source, you'll need the following:

1. Ads API Key - In your ChatGPT Ads Manager account, open the Settings tab and generate an API key.

note

Each API key is scoped to a single ad account. If you need to sync multiple ad accounts, create a separate source for each one, or contact ChatGPT advertiser support for multi-account API access.

note

During setup, the connector may not validate your API key until the first sync runs. If the key is invalid or lacks access, the sync will fail with an authentication/authorization error.

Connection Setup Guide

Once you have connected ChatGPT Ads to a destination, you will also need to configure:

• Connection Pull Schedule: Determines how frequently data is extracted from the source.
• Backfill (Days): Specifies the duration for which historical data will be retrieved during each connection run.
• Destination specific settings: Different settings such as "Dataset Name" or "Target Schema" (depending on your destination).
• Schema Migration Policy: Controls how Extract will handle schema changes from the source.

If you are configuring the ChatGPT Audiences destination, note the following connection requirements:

• Load mode: Must be Append.
• Diffing / action mapping: Each record must include the required diff_result action (Added, Changed, or Removed), or you must enable Perform Diffing so Extract can compute these actions from a full source snapshot.

Configuration

Provide the following configuration when setting up the ChatGPT Ads Conversions API destination.

• API key (api_key)
  Your ChatGPT Ads API key. This key is used to authenticate requests to the Conversions API.

• Continue on errors (continue_on_errors)
  If enabled, the connector will continue sending subsequent events even if some events fail.

• Pixel ID (pixel_id)
  The ChatGPT Ads Pixel ID to send conversion events to.

• Amounts in major units (amounts_in_major_units)
  Controls how the connector interprets data.amount (and data.contents[].amount when present):

  • Disabled (default): amounts are treated as minor units (for example, cents).
  • Enabled: amounts are treated as major units (for example, dollars).

If you are configuring the ChatGPT Audiences destination, provide the following configuration instead:

• API key
  Your ChatGPT Ads API key. Must be a non-empty token (no line breaks). This key is used to authenticate requests to the Audiences API.

Stream-level settings

• Pixel ID (pixel_id)
  The ChatGPT Ads Pixel ID to attribute events to. This is required for each stream.

Event shape and required fields

Each record you send represents a single event.

Required top-level fields:

• type (string)
  Event type. If type is custom, you must also provide custom_event_name.

• timestamp_ms (integer)
  Event timestamp in milliseconds since epoch. Events older than 7 days are rejected.

• data.* (one or more fields)
  Event payload fields must be provided using flattened keys prefixed with data. (for example, data.value, data.currency). At least one data.* field is required.

Optional top-level fields:

• action_source (string)
  If action_source is web, then source_url is required.

• source_url (string)
  Required when action_source is web.

• custom_event_name (string)
  Required when type is custom. If provided for non-custom events, it is ignored.

• user (object)
  If provided, must be a JSON object.

Notes

• Null-valued fields are removed before sending.
• Do not send a nested data object. Use flattened data.* fields instead.

Data Streams

ad_account_insights

Loading ....

ad_account

Loading ....

ad_group_insights

Loading ....

ad_groups

Loading ....

ad_insights

Loading ....

ads

Loading ....

campaign_insights

Loading ....

campaigns

Loading ....

Metadata

ad_account

Loading ....

campaigns

Loading ....

ad_groups

Loading ....

ads

Loading ....

Insights (Reports)

ad_account_insights

Loading ....

campaign_insights

Loading ....

ad_group_insights

Loading ....

ad_insights

Loading ....

Notes

• Currency and amount normalization

  • The connector normalizes data.currency (and data.contents[].currency when present) to an uppercase ISO 4217-style code before sending events.
  • If data.amount is provided, it is validated and normalized. The same normalization is applied to each data.contents[].amount when data.contents is an array.
  • By default, amounts are treated as minor units (for example, cents). If your events send amounts in major units (for example, dollars), enable the stream parameter amounts_in_major_units so the connector converts them appropriately based on the event currency.
  • If an amount is invalid, the connector will reject the event with an error pointing to the specific field (for example, data.amount or data.contents[i].amount).

• Audience sync requirements and behavior

  • Audience syncs require Append loading.
  • Each record must include an action indicating whether the identifier should be Added, Changed, or Removed. You can provide this by mapping the required diff_result field, or by enabling Perform Diffing (which computes these actions from a full source snapshot).
  • If a sync is cancelled or exceeds the connector’s time limit, rerun the connection to replay the diff.