> For the complete documentation index, see [llms.txt](https://docs.hockeystack.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hockeystack.com/integrations/ad-platforms/openai-ads.md). # OpenAI Ads The OpenAI Ads integration pulls your ChatGPT ad performance data into HockeyStack, so you can analyze ad spend, clicks, and impressions alongside your marketing, revenue, and product data. The integration connects with an OpenAI advertiser API key and imports daily ad-level performance data. ### How to Connect 1. Go to **Atlas > Ingest > Integrations**. 2. Find **OpenAI Ads** and click **Connect** 3. Paste your OpenAI advertiser API key and click **Connect**. * You can generate an API key in your OpenAI Ads account under your [OpenAI Ads Settings](https://ads.openai.com/settings) 4. *(Optional)* Turn on **Auto-tagging** if you want HockeyStack to add tracking parameters to your campaigns. See Auto-Tagging below. After you connect, HockeyStack backfills up to two years of history, depending on what OpenAI makes available. ### What Data Gets Tracked as Metadata Data is stored as one row per ad per day. Ad/day rows where spend, clicks, and impressions are all zero are skipped. | Field | Description | | -------------- | --------------------------------------------------------------------------------------------- | | account\_id | The ID of the OpenAI advertiser account | | currency | The currency the account reports spend in. | | date | The day the metrics were recorded | | network | Always `OpenAI Ads` | | campaign\_id | The ID of the campaign | | campaign\_name | The name of the campaign | | adgroup\_id | The ID of the ad group | | adgroup\_name | The name of the ad group | | ad\_id | The ID of the ad | | ad\_name | The name of the ad | | utm\_source | UTM source parsed from the destination link, defaults to `openai` if the link doesn’t set one | | utm\_medium | UTM medium parsed from the destination link | | utm\_campaign | UTM campaign parsed from the destination link | | utm\_term | UTM term parsed from the destination link. | | utm\_content | UTM content parsed from the destination link | | cost | Total spend for the ad on that day | | clicks | Total clicks for the ad on that day | | impressions | Total impressions for the ad on that day | ### High-Level Integration Flow 1. **Authentication** * HockeyStack connects to the OpenAI Ads API with your advertiser API key. 2. **Initial Backfill** * On first connection, HockeyStack imports up to two years of history, subject to what OpenAI makes available. 3. **Daily Import** * Imports run once a day and pull data through the previous day. * Days are defined by the advertiser account's timezone. 4. **Data Formatting** * Account, campaign, ad group, and ad details are combined with daily spend, clicks, and impressions. * Standard UTM parameters are parsed from each ad's destination link. 5. **Data Insertion** * The formatted data is stored under **Paid Ads** with the network `OpenAI Ads`. ### Reporting in HockeyStack * Find OpenAI Ads data under **Paid Ads**, filtered by the Ad Network `OpenAI Ads`. * Break down spend, clicks, and impressions by account, campaign, ad group, ad, date, and UTM values. ### Auto-Tagging Auto-tagging is **off by default**. When it's on: * HockeyStack checks your campaigns every 12 hours. * It updates each campaign’s query-string template to add these tracking parameters: `oppref`, `hstk_campaign`, `hstk_creative`, and `hstk_network`. * Any other query-string parameters already in the template are kept as they are. ### Notes and Caveats * **Not currently pulled** * Platform-reported conversions or revenue * Budgets, campaign status, targeting or audience settings * Geographic or demographic data * Creative content beyond the ad ID and ad name * Custom UTM parameters * **Reconnecting** * If the API key stops working, the integration will be marked as **expired in your workspace**. Reconnect it with a valid key from **Atlas > Ingest > Integrations**. * **Data freshness** * Today's data won't appear until the next daily import, since imports only run through the previous day. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.hockeystack.com/integrations/ad-platforms/openai-ads.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.