Integration of ChatGPT Ads with BigQuery
Learn how to connect ChatGPT Ads (OpenAI Ads) to Google BigQuery using WitCloud. Authorize with an API key, pick your ad account, import up to 365 days of historical campaign performance and cost data, and keep it synchronized daily.
Updated
Introduction
This module integrates with the ChatGPT Ads API (OpenAI Advertiser API), enabling you to collect campaign performance and cost data and store it in Google Cloud BigQuery. Gain deeper insights into your data and optimize the performance of your ad campaigns.
Configuration guide
Follow the steps below to connect ChatGPT Ads with BigQuery. Once the setup is complete, your ad data will be automatically transferred to your BigQuery project.
Make sure you have access to ChatGPT Ads Manager. You need to create an API key before starting the configuration — each key grants access to a single ad account.
Module setup
Go to the Integrations section in the menu > Click Add integration.

Select ChatGPT Ads from the list of available integrations.

Enter the Collect name, e.g., "ChatGPT Ads PL".

Authorization
If you have already created a ChatGPT Ads authorization, simply pick it from the drop‑down and skip ahead to selecting the account.
You authorize it with an API key generated in ChatGPT Ads Manager.
Click Authorize.

In the Authorize window, paste the API Key copied from ChatGPT Ads Manager → Settings.

Click Create to save the authorization.

The saved authorization now appears in the Select ChatGPT Ads authorization drop‑down. Pick the one you want to use — it is labelled with the ad account name and a masked fragment of the key, so several keys stay easy to tell apart.

Back in WitCloud, choose the ChatGPT Ads account you wish to export from the Select account list.

An API key is issued per ad account, so exactly one account is available for each authorization. To collect several accounts, add a separate authorization and a separate collect for each key.
Optionally, click Show advanced settings to narrow down the Tables to collect if you don't need every table. By default all of them are collected, and at least one table is required.

Click Next to move on to the data collection settings.

Historical data and scheduling
In the Historical Data field, enter the number of days of historical data you want to fetch. During the initial setup, you can retrieve data going back up to 365 days.

A data synchronization schedule will be created automatically; each run rewrites that day's partition with the data reported for it. More information on this topic can be found here.
Click Create to complete the configuration.

Done! Your ChatGPT Ads data will now be synchronized with BigQuery, providing you with detailed insights into the performance of your ad campaigns.
Data schema
Expand the tables below to view the full data schema collected from ChatGPT Ads.
Data schema for chatgpt_ads_account
| Field Name | Mode | Type |
|---|---|---|
| date | NULLABLE | DATE |
| account_id | NULLABLE | STRING |
| account_name | NULLABLE | STRING |
| currency_code | NULLABLE | STRING |
| timezone | NULLABLE | STRING |
| id | NULLABLE | STRING |
| start_time | NULLABLE | INTEGER |
| end_time | NULLABLE | INTEGER |
| impressions | NULLABLE | INTEGER |
| clicks | NULLABLE | INTEGER |
| spend | NULLABLE | FLOAT |
| ctr | NULLABLE | FLOAT |
| cpc | NULLABLE | FLOAT |
| cpm | NULLABLE | FLOAT |
| readable_time | NULLABLE | STRING |
| ad_account_id | NULLABLE | STRING |
| ad_account_name | NULLABLE | STRING |
Data schema for chatgpt_ads_campaigns
| Field Name | Mode | Type |
|---|---|---|
| date | NULLABLE | DATE |
| account_id | NULLABLE | STRING |
| account_name | NULLABLE | STRING |
| currency_code | NULLABLE | STRING |
| timezone | NULLABLE | STRING |
| id | NULLABLE | STRING |
| start_time | NULLABLE | INTEGER |
| end_time | NULLABLE | INTEGER |
| impressions | NULLABLE | INTEGER |
| clicks | NULLABLE | INTEGER |
| spend | NULLABLE | FLOAT |
| ctr | NULLABLE | FLOAT |
| cpc | NULLABLE | FLOAT |
| cpm | NULLABLE | FLOAT |
| readable_time | NULLABLE | STRING |
| ad_account_id | NULLABLE | STRING |
| ad_account_name | NULLABLE | STRING |
| campaign_id | NULLABLE | STRING |
| campaign_name | NULLABLE | STRING |
| campaign_status | NULLABLE | STRING |
Data schema for chatgpt_ads_ad_groups
| Field Name | Mode | Type |
|---|---|---|
| date | NULLABLE | DATE |
| account_id | NULLABLE | STRING |
| account_name | NULLABLE | STRING |
| currency_code | NULLABLE | STRING |
| timezone | NULLABLE | STRING |
| id | NULLABLE | STRING |
| start_time | NULLABLE | INTEGER |
| end_time | NULLABLE | INTEGER |
| impressions | NULLABLE | INTEGER |
| clicks | NULLABLE | INTEGER |
| spend | NULLABLE | FLOAT |
| ctr | NULLABLE | FLOAT |
| cpc | NULLABLE | FLOAT |
| cpm | NULLABLE | FLOAT |
| readable_time | NULLABLE | STRING |
| ad_account_id | NULLABLE | STRING |
| ad_account_name | NULLABLE | STRING |
| campaign_id | NULLABLE | STRING |
| campaign_name | NULLABLE | STRING |
| campaign_status | NULLABLE | STRING |
| ad_group_id | NULLABLE | STRING |
| ad_group_name | NULLABLE | STRING |
| ad_group_status | NULLABLE | STRING |
Data schema for chatgpt_ads_performance
| Field Name | Mode | Type |
|---|---|---|
| date | NULLABLE | DATE |
| account_id | NULLABLE | STRING |
| account_name | NULLABLE | STRING |
| currency_code | NULLABLE | STRING |
| timezone | NULLABLE | STRING |
| id | NULLABLE | STRING |
| start_time | NULLABLE | INTEGER |
| end_time | NULLABLE | INTEGER |
| impressions | NULLABLE | INTEGER |
| clicks | NULLABLE | INTEGER |
| spend | NULLABLE | FLOAT |
| ctr | NULLABLE | FLOAT |
| cpc | NULLABLE | FLOAT |
| cpm | NULLABLE | FLOAT |
| readable_time | NULLABLE | STRING |
| ad_account_id | NULLABLE | STRING |
| ad_account_name | NULLABLE | STRING |
| campaign_id | NULLABLE | STRING |
| campaign_name | NULLABLE | STRING |
| campaign_status | NULLABLE | STRING |
| ad_group_id | NULLABLE | STRING |
| ad_group_name | NULLABLE | STRING |
| ad_group_status | NULLABLE | STRING |
| ad_id | NULLABLE | STRING |
| ad_name | NULLABLE | STRING |
| ad_status | NULLABLE | STRING |
Data schema for chatgpt_ads_conversions
| Field Name | Mode | Type |
|---|---|---|
| date | NULLABLE | DATE |
| account_id | NULLABLE | STRING |
| account_name | NULLABLE | STRING |
| currency_code | NULLABLE | STRING |
| timezone | NULLABLE | STRING |
| aggregation_level | NULLABLE | STRING |
| entity_id | NULLABLE | STRING |
| conversions | NULLABLE | INTEGER |
| click_through_conversions | NULLABLE | INTEGER |
| view_through_conversions | NULLABLE | INTEGER |
