> ## Documentation Index
> Fetch the complete documentation index at: https://docs.segmentstream.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Ads

> Connect OpenAI Ads to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Generate an API token in OpenAI Ads">
    In your OpenAI Ads Manager, generate an API token that has read access to your ad account. Each OpenAI Ads token is scoped to a single ad account — if you manage several accounts, generate one token per account and connect them as separate data sources.
  </Step>

  <Step title="Navigate to Data Sources">
    Inside the SegmentStream admin panel, navigate to the **Data Sources** page and click **+ NEW** in the top-right corner.
  </Step>

  <Step title="Select OpenAI Ads">
    Choose **OpenAI Ads** from the list.
  </Step>

  <Step title="Enter your API token">
    Paste the token into the **OpenAI Ads API token** field and continue.
  </Step>

  <Step title="Confirm the ad account">
    The **Ad account** dropdown auto-populates from the token. Select it and click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

SegmentStream reads UTM parameters from the final URL served to visitors — that is, the ad's **Target URL** combined with the campaign-level and ad-level **Query string templates**. For campaigns, ad groups, and ads to stitch correctly to sessions, your OpenAI Ads templates must include the standard `utm_*` parameters.

The connector supports OpenAI Ads' template macros for per-row substitution:

| Macro             | Substituted with  |
| ----------------- | ----------------- |
| `{ad_account_id}` | The ad account ID |
| `{campaign_id}`   | The campaign ID   |
| `{ad_group_id}`   | The ad group ID   |
| `{ad_id}`         | The ad ID         |

<Steps>
  <Step title="Open the query string template">
    In OpenAI Ads Manager, open the campaign or ad settings where the query string template is configured.
  </Step>

  <Step title="Add tracking parameters">
    Add the following to the template:

    ```plain text theme={null}
    utm_source=openai&utm_medium=cpc&utm_campaign={campaign_id}&utm_content={ad_id}
    ```

    Ad-level template values take precedence over campaign-level values on the same key. UTMs the advertiser puts directly on the ad's **Target URL** take precedence over any template values.
  </Step>

  <Step title="Save">
    Save the template. Newly served ads will start carrying the parameters immediately; already-live ads pick them up on the next refresh.
  </Step>
</Steps>

Once the template is in place, sessions will be stitched with costs at the ad level. The **Campaign** and **Ad** dimensions in SegmentStream reports will display the OpenAI Ads campaign name and ad name.

<Tip>
  If spend loads into your reports but campaigns don't appear alongside sessions, check that the query string template is applied and that `utm_source`, `utm_medium`, and `utm_campaign` all resolve to non-empty values on live ads.
</Tip>