Skip to main content

​
Getting started

1

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.
2

Navigate to Data Sources

Inside the SegmentStream admin panel, navigate to the Data Sources page and click + NEW in the top-right corner.
3

Select OpenAI Ads

Choose OpenAI Ads from the list.
4

Enter your API token

Paste the token into the OpenAI Ads API token field and continue.
5

Confirm the ad account

The Ad account dropdown auto-populates from the token. Select it and click Save.

​
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:
1

Open the query string template

In OpenAI Ads Manager, open the campaign or ad settings where the query string template is configured.
2

Add tracking parameters

Add the following to the template:
text
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.
3

Save

Save the template. Newly served ads will start carrying the parameters immediately; already-live ads pick them up on the next refresh.
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.
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.