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.

Integrations list with the Add integration button

Select ChatGPT Ads from the list of available integrations.

Integration catalog with ChatGPT Ads selected

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

Collect name field filled in with the example name 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.

Authorize button next to the authorization field

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

Authorize pop-up with the API Key field filled with a placeholder value

Click Create to save the authorization.

Create button in the authorization pop-up

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.

Select ChatGPT Ads authorization drop-down with the saved authorization

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

Select account drop-down open with the example ad account

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.

Advanced settings open with the Tables to collect field

Click Next to move on to the data collection settings.

Next button below the integration form

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.

Historical Data field filled in with 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.

Data collection settings with the Create button

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 NameModeType
dateNULLABLEDATE
account_idNULLABLESTRING
account_nameNULLABLESTRING
currency_codeNULLABLESTRING
timezoneNULLABLESTRING
idNULLABLESTRING
start_timeNULLABLEINTEGER
end_timeNULLABLEINTEGER
impressionsNULLABLEINTEGER
clicksNULLABLEINTEGER
spendNULLABLEFLOAT
ctrNULLABLEFLOAT
cpcNULLABLEFLOAT
cpmNULLABLEFLOAT
readable_timeNULLABLESTRING
ad_account_idNULLABLESTRING
ad_account_nameNULLABLESTRING
Data schema for chatgpt_ads_campaigns
Field NameModeType
dateNULLABLEDATE
account_idNULLABLESTRING
account_nameNULLABLESTRING
currency_codeNULLABLESTRING
timezoneNULLABLESTRING
idNULLABLESTRING
start_timeNULLABLEINTEGER
end_timeNULLABLEINTEGER
impressionsNULLABLEINTEGER
clicksNULLABLEINTEGER
spendNULLABLEFLOAT
ctrNULLABLEFLOAT
cpcNULLABLEFLOAT
cpmNULLABLEFLOAT
readable_timeNULLABLESTRING
ad_account_idNULLABLESTRING
ad_account_nameNULLABLESTRING
campaign_idNULLABLESTRING
campaign_nameNULLABLESTRING
campaign_statusNULLABLESTRING
Data schema for chatgpt_ads_ad_groups
Field NameModeType
dateNULLABLEDATE
account_idNULLABLESTRING
account_nameNULLABLESTRING
currency_codeNULLABLESTRING
timezoneNULLABLESTRING
idNULLABLESTRING
start_timeNULLABLEINTEGER
end_timeNULLABLEINTEGER
impressionsNULLABLEINTEGER
clicksNULLABLEINTEGER
spendNULLABLEFLOAT
ctrNULLABLEFLOAT
cpcNULLABLEFLOAT
cpmNULLABLEFLOAT
readable_timeNULLABLESTRING
ad_account_idNULLABLESTRING
ad_account_nameNULLABLESTRING
campaign_idNULLABLESTRING
campaign_nameNULLABLESTRING
campaign_statusNULLABLESTRING
ad_group_idNULLABLESTRING
ad_group_nameNULLABLESTRING
ad_group_statusNULLABLESTRING
Data schema for chatgpt_ads_performance
Field NameModeType
dateNULLABLEDATE
account_idNULLABLESTRING
account_nameNULLABLESTRING
currency_codeNULLABLESTRING
timezoneNULLABLESTRING
idNULLABLESTRING
start_timeNULLABLEINTEGER
end_timeNULLABLEINTEGER
impressionsNULLABLEINTEGER
clicksNULLABLEINTEGER
spendNULLABLEFLOAT
ctrNULLABLEFLOAT
cpcNULLABLEFLOAT
cpmNULLABLEFLOAT
readable_timeNULLABLESTRING
ad_account_idNULLABLESTRING
ad_account_nameNULLABLESTRING
campaign_idNULLABLESTRING
campaign_nameNULLABLESTRING
campaign_statusNULLABLESTRING
ad_group_idNULLABLESTRING
ad_group_nameNULLABLESTRING
ad_group_statusNULLABLESTRING
ad_idNULLABLESTRING
ad_nameNULLABLESTRING
ad_statusNULLABLESTRING
Data schema for chatgpt_ads_conversions
Field NameModeType
dateNULLABLEDATE
account_idNULLABLESTRING
account_nameNULLABLESTRING
currency_codeNULLABLESTRING
timezoneNULLABLESTRING
aggregation_levelNULLABLESTRING
entity_idNULLABLESTRING
conversionsNULLABLEINTEGER
click_through_conversionsNULLABLEINTEGER
view_through_conversionsNULLABLEINTEGER