The OpenAI Ads API key (OPENAI_ADS_API_KEY) is separate from your OPENAI_API_KEY for chat completion. Provision it at ads.openai.com → Settings → API keys, copy the value at creation (shown only once), test it via GET /ad_account, then use it to manage campaigns and pull performance data programmatically. Two paths: the AI-Advisors ChatGPT Ads integration (paste your key, view / edit / publish / analyze inside AI-Advisors with AEO overlay) or the manual curl walkthrough below.
- The key is NOT the same as your platform.openai.com key. Different env var, different base URL, different provisioning UI
- Provisioned at: ads.openai.com → Settings → API keys
- Scope: One key per ad account (agencies use each client account's own key)
- Base URL:
https://api.ads.openai.com/v1/ - Test endpoint:
GET /ad_account - Rate limits: 600 req/min per endpoint, 1,200 req/min per ad account (plus per-IP limits)
OpenAI launched its ChatGPT Ads platform on February 9, 2026 and opened the Ads Manager to every US advertiser on May 5, 2026 with no account minimum. Alongside the May 5 expansion, OpenAI shipped the Advertiser API, and it has grown since. It now covers campaign management (campaigns, ad groups, ads, and creative files, plus custom audiences, product feeds, and conversion setup) and performance reporting through its Insights endpoints, which return conversions, CPA, and ROAS alongside impressions, clicks, and spend. All of it authenticates with one credential: the OpenAI Ads API key.
The single most common mistake when developers and marketers first encounter this API is confusing the OPENAI_ADS_API_KEY with the standard OPENAI_API_KEY used for chat completion. They are two completely separate credentials, issued by two completely separate OpenAI products, with two different base URLs. This guide leads with the disambiguation and then walks both install paths: the AI-Advisors ChatGPT Ads integration (2 minutes, no curl) and the manual curl walkthrough (5 minutes, full control).
The OpenAI Ads API key is not your platform.openai.com key. Different env var, different base URL, different provisioning UI. Confusing the two returns 401 in both directions.
What the OpenAI Ads API key is (and isn't)
The OpenAI Ads API key is a bearer token that authenticates programmatic requests to OpenAI's advertising platform. Read the official API overview for the full reference; the table below isolates the differences from the chat completion key that almost everyone confuses it with on first encounter.
| Dimension | OpenAI Ads API key | OpenAI platform API key |
|---|---|---|
| Env-var name | OPENAI_ADS_API_KEY | OPENAI_API_KEY |
| Provisioned at | ads.openai.com → Settings → API keys | platform.openai.com → API keys |
| Base URL | https://api.ads.openai.com/v1/ | https://api.openai.com/v1/ |
| Scope | One ad account per key | Project or organization, multiple permissions |
| What it can do | Manage campaigns, ads, creatives, audiences, and conversion setup; read delivery and conversion reporting | Generate completions, embeddings, images, fine-tunes |
| Test endpoint | GET /ad_account | GET /models |
Prerequisites
- An Ads Manager account. Sign in at ads.openai.com. Self-serve has been open to every US advertiser since May 5, 2026 with no account minimum, and OpenAI documents a per-campaign daily minimum that varies by billing currency (US $25/day, September 2026).
- Admin access on the ad account. Ads Manager accounts have three roles: Admin, Member, and Viewer. Viewers have no write permissions, so the simplest path is to have an account Admin create the key. A ChatGPT workspace or API Platform role does not carry over; OpenAI grants Ads permissions separately.
- An idea of which environment you are using. Generate separate keys for development and production. Two keys, two ad accounts, no chance of test traffic hitting production billing.
- A secrets manager or environment-variable strategy. The key is a credential; treat it like a password. We'll cover storage best practices below.
One-click connection: AI-Advisors ChatGPT Ads integration (2 minutes)
The fastest path is the AI-Advisors ChatGPT Ads integration. Paste your OPENAI_ADS_API_KEY into the integration form and AI-Advisors uses the key to surface ChatGPT Ads campaign performance (impressions, clicks, spend, CTR, CPC, CPM) inside the AI-Advisors dashboard alongside your organic AI citation share, GA4, and Google Search Console data. The integration also enables view / edit / publish operations on campaigns and ad groups directly from inside AI-Advisors with the AEO overlay you cannot get anywhere else.
Included on the Growth plan and above. The key is encrypted at rest and never leaves AI-Advisors. You can revoke access at any time by deleting the key from the integration form or rotating it in OpenAI's Ads Manager.
Skip the manual curl walkthrough. Paste your $OPENAI_ADS_API_KEY into AI-Advisors and view, edit, publish, and analyze your ChatGPT Ads alongside your AEO data. Included on the Growth plan and above.
Connect the ChatGPT Ads integration →Manual: Provision the key at ads.openai.com (5 minutes)
If you are building your own integration or want to test the API directly with curl before connecting AI-Advisors, the manual provisioning path takes four steps. The key value is shown only once at creation, so read all four steps before clicking Create.
STEP 1: Sign in to ads.openai.com
~30 secOpen ads.openai.com in your browser and sign in with the account that has admin access to your ad account. This is a different surface from platform.openai.com (the chat completion platform) and from chatgpt.com (the consumer product). Make sure you are on the Ads Manager interface before continuing.
STEP 2: Open the Settings tab and navigate to API keys
~1 minIn Ads Manager, click Settings in the left navigation, then locate the API keys section. The interface lists existing keys (if any) with their name, creation date, and last-used timestamp. The value itself is never shown after creation, so the list is for management (rotation, revocation) rather than retrieval.
STEP 3: Click Create new key and copy the value immediately
~1 minClick Create new key, name it descriptively (e.g. main-account-prod or backfill-script-dev), and copy the value the moment it appears. The key is shown only once at creation. Paste it into your secrets manager, env-var file, or password manager before closing the modal.
The key itself stays valid in OpenAI's system, but you cannot recover the secret. Generate a new key, swap it into your environment, then revoke the old one. This protects against accidental leaks even when you forget to delete the unrecoverable original.
STEP 4: Test the key with GET /ad_account
~30 secExport the key as an environment variable and run a curl request against the canonical test endpoint:
export OPENAI_ADS_API_KEY="<paste the value from step 3>"
curl -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
-H "Accept: application/json" \
https://api.ads.openai.com/v1/ad_accountA successful response returns the ad account's ID, name, URL, status, timezone, currency, and brand review status. OpenAI recommends checking the currency, timezone, account status, and reviews before you create a campaign, because an account marked active can still have a review outstanding. A 401 Unauthorized response means the key is wrong (typo, expired, revoked) or you are pointing at the wrong base URL (likely api.openai.com instead of api.ads.openai.com).
What the Insights API exposes
Once the key is verified, the Insights API gives you performance data across four scopes (ad_account / campaign / ad_group / ad). Delivery metrics are impressions, clicks, spend, CTR, CPC, and CPM. Conversions are documented outputs as well: conversions (goal conversions from clicks plus views), cpa (spend divided by conversions), post_click_cvr, attributed sales, and ROAS. OpenAI added its conversion setup and reporting endpoints on June 3, 2026 and selectable attribution windows on September 30, 2026.
The windows are a 7, 14, or 30-day click window (default 30) and a 0 or 1-day view window (default 1). They change what reporting counts, not your campaign's conversion goal or optimization settings, and they leave impressions, clicks, and spend untouched. The conversions themselves still reach OpenAI through the Measurement Pixel or the Conversions API; Insights is where you read them back.
# Daily account-level delivery and conversions for one week.
# Conversion metrics need full days in your ad account's timezone
# (GET /ad_account returns it).
curl -G "https://api.ads.openai.com/v1/ad_account/insights" \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
--data-urlencode 'aggregation_level=ad_account' \
--data-urlencode 'time_granularity=daily' \
--data-urlencode 'time_ranges[]={"type":"date_range","since":"2026-10-01","until":"2026-10-07","timezone":"America/New_York"}' \
--data-urlencode 'fields[]=readable_time' \
--data-urlencode 'fields[]=impressions' \
--data-urlencode 'fields[]=clicks' \
--data-urlencode 'fields[]=spend' \
--data-urlencode 'fields[]=conversions' \
--data-urlencode 'fields[]=cpa'Pagination uses cursor-based before and after parameters, with up to 2,000 rows per page. time_granularity accepts hourly, daily (the default), monthly, or none; aggregation_level can be set to ad_account, campaign, ad_group, or ad to control the row shape of the response. Requests for conversion metrics can span at most 365 days. For a focused conversion report, POST /v1/conversions/insights splits goal conversions into click-through and view-through counts, with optional per-event detail.
Object status model
For an ad to actually show to users, every level of the hierarchy has to be ready. OpenAI's troubleshooting guide checks four levels:
- The ad account is active. Its brand review is complete and no spend limit is exhausted.
- The campaign is active. It is within its schedule and has budget left. A paused campaign stops an active ad from serving.
- The ad group is active. Pausing an ad group stops all of its ads, whatever their own status. Toggling state via the Advertiser API is one of the most common operations.
- The ad is active and approved. Monitor the
review_statusfield on each ad. An ad with statusactiveand review statusin_reviewis enabled but cannot serve until the review passes, and editing its creative starts a new review.
Rate limits and multi-account access
The Advertiser API enforces two limits simultaneously:
- 600 requests per minute per endpoint
- 1,200 requests per minute overall per ad account
Both are also enforced by IP address, so a single request must stay within all four ceilings (per-endpoint per-account, overall per-account, per-endpoint per-IP, overall per-IP) at the same time. Creating bulk jobs has a separate limit of 10 requests per 10 seconds per ad account. For most marketing workflows the limits are not constraining; bulk operations like backfilling six months of campaign-level insights can hit the cap if you do not paginate carefully.
Each API key is scoped to one ad account. Agencies managing multiple client accounts and enterprises with separate business units need one key per ad account; OpenAI's API Partner Setup guide tells partners to use the key associated with each client account and to confirm it with GET /ad_account before configuring anything. Some partner capabilities, such as pixel management, Conversions API key creation, and conversion-optimized bidding, must also be enabled for the client account; if those calls return 403 or 404, the guide says to contact your OpenAI partner representative.
Security best practices
- Store as an environment variable. Never hard-code the key in source. Use
process.env.OPENAI_ADS_API_KEY(Node),os.environ["OPENAI_ADS_API_KEY"](Python), or your platform's secrets manager (AWS Secrets Manager, Doppler, 1Password Connect, Vercel encrypted env vars). - Keep
.envin.gitignore. Committing the key to a public or private repo creates a permanent leak. Usegit-secretsor a pre-commit hook to prevent accidental commits. - Rotate on a schedule. Most teams rotate every 90 days, plus immediately if there is any suspicion the key has been exposed (departing employee, accidental commit, third-party breach, agency offboarding).
- Separate development and production keys. One key per environment, scoped to its own ad account. Test traffic should never hit production billing.
- Restrict by IP if your stack supports it. Most secrets-manager solutions support source-IP allowlisting at the runtime layer; combined with the API's per-IP rate limit, this provides defense in depth.
Common mistakes
- Confusing with platform.openai.com keys. The #1 mistake. The chat completion key (
OPENAI_API_KEY) cannot authenticate Advertiser API requests; the Ads key cannot authenticate chat completion. Both fail with 401. - Pointing at the wrong base URL. Use
https://api.ads.openai.com/v1/for the Ads API. The platform key's base URL ishttps://api.openai.com/v1/. - Not copying the value at creation. The key is shown only once. If you close the modal without copying, generate a new key (the original stays valid but unrecoverable).
- Assuming one key covers several ad accounts. Each key is scoped to exactly one ad account, so every request acts on that account. Run
GET /ad_accountto confirm which account a key belongs to before you change anything. - Sending conversion events with the Ads API key. The Conversions API uses its own Conversions API key and a separate host, not
OPENAI_ADS_API_KEY. The Ads API key can create Conversions API keys for accounts where that is enabled, but it does not send events. - Forgetting that ads must pass review. Even if the ad, ad group, and campaign are all active, an ad whose
review_statusis stillin_reviewwill not serve.
Pair with the Measurement Pixel for end-to-end tracking
The API key handles the management and reporting side of your campaigns. For the measurement side (conversions back from your site to OpenAI), you also need the JavaScript Measurement Pixel installed via Google Tag Manager, the Conversions API, or both. Once events flow, the same Ads API key reads the results back through Insights. See our companion post on how to install the ChatGPT Ads Measurement Pixel via GTM. For the full strategic picture of why both the pixel and the API key matter, see our deep-dive on ChatGPT Ads conversion tracking.
The API key manages and reports. The pixel measures and attributes. Both run from the same ad account; both belong in your stack.
Skip the manual provisioning, secrets-manager setup, and per-endpoint plumbing. Paste your $OPENAI_ADS_API_KEY into AI-Advisors and view, edit, publish, and analyze your ChatGPT Ads campaigns overlayed with your AEO data.
Connect the ChatGPT Ads integration →Frequently Asked Questions
#Is the OpenAI Ads API key the same as my OpenAI platform API key?
No. They are two different credentials issued by two different OpenAI products. The OpenAI Ads API key (OPENAI_ADS_API_KEY) is provisioned in the Settings tab of ads.openai.com and authenticates requests to the Advertiser API and Insights API at https://api.ads.openai.com/v1/. The standard OPENAI_API_KEY is provisioned at platform.openai.com and authenticates chat completion, embedding, image generation, and other model API requests at https://api.openai.com/v1/. They cannot be used interchangeably. A request to the Advertiser API with a platform.openai.com key returns 401 Unauthorized.
#Where in Ads Manager do I find the API key?
Sign in to ads.openai.com, click the Settings tab in the left navigation, and look for the API keys section. Click Create new key, name it, and copy the value. The key is shown only once at creation. If you do not copy it now, generate a new key (the old one stays valid but the value is unrecoverable).
#Can one API key manage multiple ad accounts?
No. Each OpenAI Ads API key is scoped to exactly one ad account. Agencies managing multiple client accounts, or enterprises with separate business units, need a separate key per account: OpenAI's API Partner Setup guide tells partners to use the API key associated with each client ad account they configure. Run GET /ad_account with each key to confirm which account it belongs to before you change anything.
#What can I do with the OpenAI Ads API key?
Manage and report on one ad account in code. OpenAI describes the Advertiser API as the way to create and manage campaigns, ad groups, ads, product feeds, conversion tracking, and reporting. That covers campaigns, ad groups, and ads (including previews), creative image uploads, custom audiences, product feeds, bulk jobs, audit logs, and conversion setup (pixels, Conversions API keys, and event settings). The Insights endpoints report impressions, clicks, spend, CTR, CPC, and CPM at four scopes (ad_account, campaign, ad_group, ad), and conversions are now documented outputs too: conversions, cost per action (CPA), post-click conversion rate, attributed sales, and ROAS, with selectable click and view attribution windows. Conversion events themselves still reach OpenAI through the Measurement Pixel or the Conversions API, which uses its own Conversions API key rather than this one.
#What happens if I lose my OpenAI Ads API key?
The key value is shown only once at creation. If you lose the value, the key itself stays valid in OpenAI's system but you cannot recover the secret. The fix: generate a new key in the Settings tab, swap it into your environment (env var, secrets manager, or the AI-Advisors ChatGPT Ads integration field), then revoke the old key. Treat the key like a password: never commit it to git, never paste it into a public document, and rotate it on a schedule.
#What rate limits does the OpenAI Ads API enforce?
Two limits enforced together: 600 requests per minute per endpoint, and 1,200 requests per minute overall per ad account. Both are also enforced by IP address, so a request must stay within all four ceilings (per-endpoint per-account, overall per-account, per-endpoint per-IP, overall per-IP) simultaneously. Creating bulk jobs has its own limit of 10 requests per 10 seconds per ad account. For most marketing workflows the limits are not constraining, but bulk operations like backfilling six months of campaign-level insights can hit the limit if you do not paginate carefully.
Related Reading
- How to install the ChatGPT Ads Measurement Pixel via Google Tag Manager
- ChatGPT Ads Conversion Tracking Is Real: What OpenAI's April 30 Privacy Policy Update Tells You About the Roadmap
- How to Report on ChatGPT Ad Campaigns: A 2026 Measurement Stack
- How to Use ChatGPT Ads: A Marketer's Step-by-Step Guide (2026)
- What Are ChatGPT Ads? The Complete Guide for 2026
- How to Measure ROI for ChatGPT Ads: The 2026 ROAS Framework for B2B Marketers
