OpenAI Ads (ChatGPT) Data Connector

Follow
Avatar
Fernando Cabral
Updated
Setting Up OpenAI Ads
Cost Aggregation
Set up data connector

 

Add the Data Connector

  1. In Data Integrations > Data Connectors, click Add Data Connector and type search for the connector “ChatGPT (OpenAI Ads)”.

     
  2. Paste in your OpenAI Ads API key. To generate one, go to your OpenAI Ads Manager account, open the Settings tab, and generate an API key.

  3. Click Submit.
     

Quick Details

API Version API (OpenAI Ads API v1, https://api.ads.openai.com/v1)
Authentication Bearer API key, generated in OpenAI Ads Manager under Settings. One key per ad account.
Data breakdown (segmentation)

OpenAI Ads provides your data broken down by all of the following (see Data Mapping below for terminology):

  • Account
  • Campaign
  • Sub-Campaign (OpenAI "Ad Group")
  • Creative (OpenAI "Ad")

Country is additionally derived from each campaign's targeting settings rather than returned as a reporting breakdown. See Known Limitations.
How far back we pull data Every day, Singular pulls data from 7 days back.
Time zone The time zone configured in the OpenAI account.
Is data available on the creative (ad) level? Yes.
Does Singular show your creative assets? Yes. Singular pulls each ad's creative type, title, body, target URL, and image URL.
Known Limitations/ Issues See Known Limitations below.

Data Mapping

Notes on Terminology:

  • "Campaign" in Singular corresponds to "Campaign" in OpenAI Ads
  • "Sub-Campaign" corresponds to OpenAI's "Ad Group"
  • "Creative" corresponds to OpenAI's "Ad"

For descriptions of all the fields, see the Singular Metrics and Dimensions Glossary.

Field in Singular UI Field in Singular API Field in OpenAI Ads
Dimensions
Account ID adn_account_id id from /v1/ad_account
Account Name adn_account_name name from /v1/ad_account
Network Campaign ID adn_campaign_id campaign_id
Network Campaign Name adn_campaign_name campaign_name
Network Sub Campaign ID adn_sub_campaign_id ad_group_id
Network Sub Campaign Name adn_sub_campaign_name ad_group_name
Network Creative ID adn_creative_id ad_id
Network Creative Name adn_creative_name ad_name
Country country_field Derived from the campaign's targeting.locations.countries
Date date_field Given as a parameter when querying OpenAI Ads (time_ranges[], daily granularity)
Metrics
Cost adn_cost spend
Impressions adn_impressions impressions
Clicks adn_clicks clicks

Costs are reported in the ad account's currency, taken from currency_code on the OpenAI ad account.

Creative assets

Singular enriches each ad with creative metadata pulled from OpenAI's /v1/ads endpoint: creative type, title, body, target URL, and image URL, plus the ad's status and review status. These power creative previews and Creative IQ reporting.

 

FAQ and Troubleshooting

What metrics does Singular pull from OpenAI Ads?

Out of the metrics provided by OpenAI Ads, the Singular integration gathers those relevant to performance marketing:

  • Impressions
  • Clicks
  • Cost

OpenAI Ads currently does not report installs or conversions back through the reporting API, so the Installs metric in your Singular reports only comes from Singular's own attribution.

Why don't I see conversion or install data from OpenAI in my cost reports?

OpenAI's reporting API returns spend, impressions, and clicks. Attributed installs and in-app events come from Singular's attribution pipeline and are joined to OpenAI cost on the shared Campaign, Sub-Campaign, and Creative IDs. This is what allows Singular to show ROI and eROAS on OpenAI Ads spend.

For this join to work, your campaigns must be using Singular tracking links. See the OpenAI Ads Attribution guide.
 

Can I pull more than one OpenAI ad account into Singular?

 

Yes, but each API key covers one ad account, so you need one data connector per ad account. Alternatively, request multi-account API access from OpenAI advertiser support.

Can I get the raw OpenAI Ads data in my own warehouse?

Yes. Singular's Extract product can deliver OpenAI Ads data directly to your BI stack, including campaign, ad group, ad, and insights streams. See OpenAI Ads as an Extract source.

 

Known Limitations
  • One API key per ad account. Multiple ad accounts require multiple data connectors unless OpenAI grants multi-account API access.
  • Country is derived from campaign targeting, and reflects only the first targeted country. OpenAI's insights endpoint does not return a geo breakdown, so Singular relies the campaign's targeting settings instead. For a campaign targeting multiple countries, only the first country in the targeting list is reported as the 'Country' dimension by default.