Skip to main content

OpenAI Ads

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

info

API Documentation: OpenAI Ads API Overview | Authentication Reference

Setup Guide​

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

  1. Ads API Key - In your OpenAI 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 OpenAI 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 OpenAI 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.

Configuration​

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

  • API key (api_key)
    Your OpenAI 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.

Stream-level settings​

  • Pixel ID (pixel_id)
    The OpenAI 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.

Schema ERD​

Explore the interactive entity relationship diagram for OpenAI Ads.

Open page

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 ....