Integrations
OpenAI Ads
40 actions for OpenAI Ads.
Add ChatGPT Ads Custom Audience Members#
Adds members to a custom audience. Identifiers are objects with type and value; provide at most 10,000.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsAddCustomAudienceMembers · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Custom Audience ID | Text | Yes | (empty) | ID of the custom audience. |
| Identifiers | Object | Yes | — | JSON array of {type, value} identifier objects, with a maximum of 10,000. |
| Expected Revision | Number | No | 0 | Optional audience revision expected before the update. |
Outputs#
| Output | Type |
|---|---|
| Operation | Object |
Use as an agent tool#
Tool name: openai_ads_add_custom_audience_members
MUTATES LIVE ADVERTISING STATE. Add 1 to 10,000 inline identifiers to a ChatGPT Ads custom audience with an internally generated idempotency key.
Archive ChatGPT Ads Custom Audience#
Archives a custom audience permanently. This action is irreversible.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsArchiveCustomAudience · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Custom Audience ID | Text | Yes | (empty) | ID of the custom audience to archive. |
Outputs#
| Output | Type |
|---|---|
| Audience | Object |
Use as an agent tool#
Tool name: openai_ads_archive_custom_audience
MUTATES LIVE ADVERTISING STATE. Archive a ChatGPT Ads custom audience. This action is irreversible.
Create ChatGPT Ad#
Creates a ChatGPT ad from a creative. Title is 3-50 characters and body at most 100.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsCreateAd · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Ad Group ID | Text | Yes | (empty) | The parent ad group. |
| Name | Text | Yes | (empty) | Internal ad name (3-1000 characters), never shown to users. |
| Status | Text | No | paused | Required by the API: active or paused. Defaults to paused so a flow never starts spending without being asked to. |
| Creative | Object | Yes | — | e.g. {“type”:“chat_card”,“title”:"…",“body”:"…",“target_url”:“https://…”,“file_id”:"…"}. |
| Idempotency Key | Text | No | (empty) | Optional. Reuse the same value when retrying a create that failed for an unknown reason — the original entity is returned instead of a second one being made. |
Outputs#
| Output | Type |
|---|---|
| Ad | Object |
Use as an agent tool#
Tool name: openai_ads_create_ad
MUTATES LIVE ADVERTISING STATE. Create a ChatGPT ad. For a chat_card creative, title is 3-50 characters, body at most 100, and both target_url and file_id are required - upload the image first with openai_ads_upload_file. New ads enter review and serve only once approved.
Create ChatGPT Ads Ad Group#
Creates a ChatGPT Ads ad group with targeting intent and bid configuration.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsCreateAdGroup · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Campaign ID | Text | Yes | (empty) | The parent campaign. |
| Name | Text | Yes | (empty) | Ad group name (3-1000 characters). |
| Description | Text | No | (empty) | Optional internal notes. |
| Status | Text | No | paused | Required by the API: active or paused. Defaults to paused so a flow never starts spending without being asked to. |
| Context Hints | Object | No | — | Targeting intent phrases as a JSON array (up to 2000). |
| Bidding Config | Object | No | — | e.g. {“billing_event_type”:“click”,“max_bid_micros”:250000}. |
| Product Set | Object | No | — | e.g. {“product_feed_id”:“product_feed_123”,“filters”:[{“field”:“brand”,“operator”:“in”,“values”:[“Acme”]},{“field”:“star_rating”,“operator”:“gte”,“values”:[“4.5”]}]}. Fields: title, body, item_id, offer_id, price, target_url, image_url, product_category, brand, seller_name, external_seller_id, star_rating, condition, age_group. Operators: in, or gt/gte/lt/lte on price and star_rating only. One filter per field; values are always strings. The feed id is the campaign’s own, as shown in Ads Manager under Feeds. |
| Idempotency Key | Text | No | (empty) | Optional. Reuse the same value when retrying a create that failed for an unknown reason — the original entity is returned instead of a second one being made. |
Outputs#
| Output | Type |
|---|---|
| Ad Group | Object |
Use as an agent tool#
Tool name: openai_ads_create_ad_group
MUTATES LIVE ADVERTISING STATE. Create a ChatGPT Ads ad group. context_hints carry the targeting intent (up to 2000 entries). bidding_config.max_bid_micros is in micros.
Create ChatGPT Ads Campaign#
Creates a ChatGPT Ads campaign. Budgets are in micros (1000000 = 1.00).
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsCreateCampaign · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Name | Text | Yes | (empty) | Campaign name (3-1000 characters). |
| Description | Text | No | (empty) | Optional internal notes. |
| Budget | Object | No | — | Spend limits in micros, e.g. {“lifetime_spend_limit_micros”: 50000000}. |
| Bidding Type | Text | No | (empty) | What to bid on: impressions, clicks or conversions. Defaults to impressions. |
| Conversion Event Setting IDs | Object | No | — | Exactly one active event setting when bidding type is conversions — the API rejects none and rejects more than one, and the choice cannot be changed afterwards. |
| Targeting | Object | No | — | Geo targeting, e.g. {“locations”:{“include”:[{“id”:"<location id>"}]}}. |
| Status | Text | No | paused | Required by the API: active or paused. Defaults to paused so a flow never starts spending without being asked to. |
| Mode | Text | No | (empty) | Set to product_feed for a catalogue campaign, whose ad groups advertise products from a feed. Fixed at creation. |
| Product Feed ID | Text | No | (empty) | The feed a product_feed campaign draws from, as shown in Ads Manager under Feeds. Must be linked to this ad account; no endpoint lists the feeds, so it has to be supplied. |
| Idempotency Key | Text | No | (empty) | Optional. Reuse the same value when retrying a create that failed for an unknown reason — the original entity is returned instead of a second one being made. |
Outputs#
| Output | Type |
|---|---|
| Campaign | Object |
Use as an agent tool#
Tool name: openai_ads_create_campaign
MUTATES LIVE ADVERTISING STATE. Create a ChatGPT Ads campaign. budget.lifetime_spend_limit_micros is in micros and must be at least 1000000 (= 1.00 in the account currency). Conversion bidding also requires conversion_event_setting_ids.
Create ChatGPT Ads Conversions API Key#
Mints a server-to-server Conversions API key. The secret is returned only once.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsCreateConversionsApiKey · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Name | Text | Yes | (empty) | Key name (3-1000 characters). |
Outputs#
| Output | Type |
|---|---|
| Api Key | Object |
Use as an agent tool#
Tool name: openai_ads_create_conversions_api_key
MUTATES LIVE ADVERTISING STATE. Mint a ChatGPT Ads Conversions API key for server-to-server event reporting. The secret is returned ONCE and cannot be retrieved again - hand it to the user immediately and never log it.
Create ChatGPT Ads Custom Audience#
Creates an empty custom audience; add members separately. File-backed audience creation is available only in Ads Manager/dashboard.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsCreateCustomAudience · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Name | Text | Yes | (empty) | Name for the custom audience. |
| Description | Text | No | (empty) | Optional description of the audience. |
Outputs#
| Output | Type |
|---|---|
| Audience | Object |
Use as an agent tool#
Tool name: openai_ads_create_custom_audience
MUTATES LIVE ADVERTISING STATE. Create an empty ChatGPT Ads custom audience. Add inline members separately; file-based creation is dashboard-only.
Create ChatGPT Ads Conversion Event#
Defines a conversion event, which is what unlocks conversion bidding.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsCreateEventSetting · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Name | Text | Yes | (empty) | Event setting name. |
| Event Type | Text | Yes | order_created | order_created, lead_created, registration_completed or custom. |
| Source IDs | Object | Yes | — | Exactly one pixel id, as a JSON array. |
| Attribution Window (days) | Number | No | 30 | Attribution window in days, typically 30. |
| Custom Event Name | Text | No | (empty) | Required when event type is custom. |
Outputs#
| Output | Type |
|---|---|
| Event Setting | Object |
Use as an agent tool#
Tool name: openai_ads_create_event_setting
MUTATES LIVE ADVERTISING STATE. Define a ChatGPT Ads conversion event. source_ids takes exactly one pixel id, and event_type=custom also requires custom_event_name. This is what unlocks conversion bidding on a campaign.
Create ChatGPT Ads Pixel#
Creates a web conversion pixel and returns its pixel_id for site installation.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsCreatePixel · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Name | Text | Yes | (empty) | Pixel name (3-1000 characters). |
Outputs#
| Output | Type |
|---|---|
| Pixel | Object |
Use as an agent tool#
Tool name: openai_ads_create_pixel
MUTATES LIVE ADVERTISING STATE. Create a ChatGPT Ads web conversion pixel and return its pixel_id for installation on the site.
Get ChatGPT Ad#
Reads one ad by id, including its creative and review status.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsGetAd · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Ad ID | Text | Yes | (empty) | The ad to read. |
Outputs#
| Output | Type |
|---|---|
| Ad | Object |
Use as an agent tool#
Tool name: openai_ads_get_ad
Get one ChatGPT ad by id, including its creative and review_status. A review_status of ‘rejected’ means the ad serves nothing even while its status is active.
Get ChatGPT Ad Account#
Reads the ChatGPT ad account: name, status, timezone, currency, review status and budget limits.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsGetAdAccount · Beta
Outputs#
| Output | Type |
|---|---|
| Ad Account | Object |
Use as an agent tool#
Tool name: openai_ads_get_ad_account
Get the ChatGPT ad account including name, status, timezone, currency code, review status and daily/lifetime budget limits in micros.
Get ChatGPT Ads Ad Group#
Reads one ad group by id, including context hints and bid configuration.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsGetAdGroup · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Ad Group ID | Text | Yes | (empty) | The ad group to read. |
Outputs#
| Output | Type |
|---|---|
| Ad Group | Object |
Use as an agent tool#
Tool name: openai_ads_get_ad_group
Get one ChatGPT Ads ad group by id, including its context hints, billing event type and max bid in micros.
Get ChatGPT Ads Bulk Job#
Reads a bulk mutation job’s status and operation count.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsGetBulkJob · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Job ID | Text | Yes | (empty) | The bulk job to read. |
Outputs#
| Output | Type |
|---|---|
| Job | Object |
Use as an agent tool#
Tool name: openai_ads_get_bulk_job
Get a ChatGPT Ads bulk mutation job’s status (pending, in_progress, completed, partially_failed, failed) and operation count.
Get ChatGPT Ads Campaign#
Reads one campaign by id, including budget, bidding type and targeting.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsGetCampaign · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Campaign ID | Text | Yes | (empty) | The campaign to read. |
Outputs#
| Output | Type |
|---|---|
| Campaign | Object |
Use as an agent tool#
Tool name: openai_ads_get_campaign
Get one ChatGPT Ads campaign by id, including its budget, bidding type, schedule and location targeting.
Get ChatGPT Ads Conversion Insights#
Gets conversion insights for selected entities and time ranges.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsGetConversionInsights · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Aggregation Level | Text | Yes | (empty) | Level used to aggregate the conversion insights. |
| Entity IDs | Object | No | — | JSON array of entity IDs to include. |
| Time Ranges | Object | No | — | JSON array of time ranges to query. |
Outputs#
| Output | Type |
|---|---|
| Rows | List |
| Has More | Yes/No |
| Last Id | Text |
Use as an agent tool#
Tool name: openai_ads_get_conversion_insights
Query ChatGPT Ads conversion insights by aggregation level, entity IDs, and time ranges.
Get ChatGPT Ads Custom Audience#
Gets one custom audience by ID.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsGetCustomAudience · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Custom Audience ID | Text | Yes | (empty) | ID of the custom audience. |
Outputs#
| Output | Type |
|---|---|
| Audience | Object |
Use as an agent tool#
Tool name: openai_ads_get_custom_audience
Get one ChatGPT Ads custom audience by id, including its status and revision.
Get ChatGPT Ads Custom Audience Operation#
Gets the status of a custom audience operation.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsGetCustomAudienceOperation · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Custom Audience ID | Text | Yes | (empty) | ID of the custom audience. |
| Operation ID | Text | Yes | (empty) | ID of the custom audience operation. |
Outputs#
| Output | Type |
|---|---|
| Operation | Object |
Use as an agent tool#
Tool name: openai_ads_get_custom_audience_operation
Poll a ChatGPT Ads custom-audience operation and return its current live status.
Get ChatGPT Ads Insights#
Queries ChatGPT Ads performance insights at any level, with optional filters, sorting and segment breakdown.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsGetInsights · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Campaign ID | Text | No | (empty) | Scope to one campaign. Leave empty for the whole account. |
| Ad Group ID | Text | No | (empty) | Scope to one ad group. |
| Ad ID | Text | No | (empty) | Scope to one ad. |
| Aggregation Level | Text | No | (empty) | Which entity each row describes: ad_account, campaign, ad_group or ad. |
| Time Granularity | Text | No | daily | Row bucketing: hourly, daily, monthly or none. Defaults to daily. |
| Time Ranges | Object | No | — | Time ranges as a JSON array, e.g. [{“type”:“date_range”,“since”:“2026-07-01”,“until”:“2026-07-31”}]. hour_range uses the same since/until as YYYY-MM-DDTHH; unix_range uses start/end as unix seconds, never since/until. Both local types take an optional IANA timezone. |
| Fields | Object | No | — | Restrict the returned columns, e.g. [“impressions”,“spend”]. |
| Filters | Object | No | — | Filter objects, e.g. [{“field”:“ctr”,“operator”:“LESS_THAN”,“value”:0.005}]. Operators: IN, GREATER_THAN, LESS_THAN. |
| Sort | Object | No | — | Sort objects, e.g. [{“field”:“spend”,“direction”:“desc”}]. Applied before pagination. |
| Segments | Object | No | — | Breakdown dimension as a JSON array with at most one of product, country, device. |
| Includes | Object | No | — | Expansion that surfaces zero-impression rows: [“zero_impression_products”], which requires segments [“product”]. |
| Limit | Number | No | 0 | Rows per page (1-2000). |
| After Cursor | Text | No | (empty) | Cursor from a previous response’s last_id, to page forward. |
| Before Cursor | Text | No | (empty) | Cursor from a previous response’s first_id, to page back. |
Outputs#
| Output | Type |
|---|---|
| Rows | List |
| Has More | Yes/No |
| Last Id | Text |
Use as an agent tool#
Tool name: openai_ads_get_insights
Query ChatGPT Ads performance insights. Metrics: impressions, clicks, spend, ctr, cpc, cpm. Scope narrows to whichever id is supplied (none = whole ad account). Use filters for thresholds (e.g. find ads under 0.5% CTR), sort to rank, and segments for a country/device/product breakdown (at most one). Pass includes with zero_impression_products to surface catalogue items that never served.
List ChatGPT Ads Ad Groups#
Lists ad groups within a campaign.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsListAdGroups · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Campaign ID | Text | Yes | (empty) | The campaign whose ad groups to list. |
| Limit | Number | No | 0 | Rows per page (1-2000). |
| After Cursor | Text | No | (empty) | Cursor from a previous response’s last_id, to page forward. |
| Before Cursor | Text | No | (empty) | Cursor from a previous response’s first_id, to page back. |
Outputs#
| Output | Type |
|---|---|
| Ad Groups | List |
| Has More | Yes/No |
| Last Id | Text |
Use as an agent tool#
Tool name: openai_ads_list_ad_groups
List ad groups in a ChatGPT Ads campaign. Returns ids, names, statuses, context hints and bid configuration.
List ChatGPT Ads#
Lists ads within an ad group, including their review status.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsListAds · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Ad Group ID | Text | Yes | (empty) | The ad group whose ads to list. |
| Limit | Number | No | 0 | Rows per page (1-2000). |
| After Cursor | Text | No | (empty) | Cursor from a previous response’s last_id, to page forward. |
| Before Cursor | Text | No | (empty) | Cursor from a previous response’s first_id, to page back. |
Outputs#
| Output | Type |
|---|---|
| Ads | List |
| Has More | Yes/No |
| Last Id | Text |
Use as an agent tool#
Tool name: openai_ads_list_ads
List ads in a ChatGPT Ads ad group. Returns ids, names, statuses and review_status - a review_status of ‘rejected’ means the ad serves nothing even while active.
List ChatGPT Ads Bulk Job Operations#
Lists per-operation results for a bulk job, with error codes and retryability.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsListBulkJobOperations · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Job ID | Text | Yes | (empty) | The bulk job whose operations to list. |
| Limit | Number | No | 0 | Rows per page (1-2000). |
| After Cursor | Text | No | (empty) | Cursor from a previous response’s last_id, to page forward. |
| Before Cursor | Text | No | (empty) | Cursor from a previous response’s first_id, to page back. |
Outputs#
| Output | Type |
|---|---|
| Operations | List |
| Has More | Yes/No |
| Last Id | Text |
Use as an agent tool#
Tool name: openai_ads_list_bulk_job_operations
List per-operation results for a ChatGPT Ads bulk job, including status, resource_id, error_code and whether each failure is retryable.
List ChatGPT Ads Campaigns#
Lists campaigns in the ChatGPT ad account, one cursor page at a time.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsListCampaigns · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Limit | Number | No | 0 | Rows per page (1-2000). |
| After Cursor | Text | No | (empty) | Cursor from a previous response’s last_id, to page forward. |
| Before Cursor | Text | No | (empty) | Cursor from a previous response’s first_id, to page back. |
Outputs#
| Output | Type |
|---|---|
| Campaigns | List |
| Has More | Yes/No |
| Last Id | Text |
Use as an agent tool#
Tool name: openai_ads_list_campaigns
List campaigns in the ChatGPT ad account. Returns campaign ids, names, statuses, bidding types and budgets. Supports cursor pagination via limit/after/before.
List ChatGPT Ads Custom Audiences#
Lists custom audiences with optional filters.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsListCustomAudiences · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Limit | Number | No | 0 | Maximum number of audiences to return. |
| Intended Use | Text | No | (empty) | Filter by the audience’s intended use. |
| Custom Audience IDs | Object | No | — | JSON array of custom audience IDs to include. |
| Matched Count Granularity | Text | No | (empty) | Granularity for matched member counts. |
Outputs#
| Output | Type |
|---|---|
| Audiences | List |
| Has More | Yes/No |
| Last Id | Text |
| Policy Revision | str | int |
Use as an agent tool#
Tool name: openai_ads_list_custom_audiences
List ChatGPT Ads custom audiences. Filter by intended use, audience ids, or matched-count granularity.
List ChatGPT Ads Conversion Events#
Lists conversion event definitions and the campaigns referencing them.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsListEventSettings · Beta
Outputs#
| Output | Type |
|---|---|
| Event Settings | List |
| Has More | Yes/No |
| Last Id | Text |
Use as an agent tool#
Tool name: openai_ads_list_event_settings
List ChatGPT Ads conversion event settings, including which campaigns reference each one. Conversion bidding requires at least one event setting.
List Recent ChatGPT Ads Pixel Events#
Lists recent events received by a conversion pixel.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsListRecentPixelEvents · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Pixel ID | Text | Yes | (empty) | ID of the conversion pixel. |
Outputs#
| Output | Type |
|---|---|
| Events | List |
| Response | Object |
Use as an agent tool#
Tool name: openai_ads_list_recent_pixel_events
List the recent live events received by a ChatGPT Ads conversion pixel.
Merge ChatGPT Ads Custom Audiences#
Creates a custom audience by merging 2 to 64 source audiences.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsMergeCustomAudiences · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Name | Text | Yes | (empty) | Name for the merged custom audience. |
| Custom Audience IDs | Object | Yes | — | JSON array of 2 to 64 custom audience IDs to merge. |
Outputs#
| Output | Type |
|---|---|
| Audience | Object |
Use as an agent tool#
Tool name: openai_ads_merge_custom_audiences
MUTATES LIVE ADVERTISING STATE. Merge 2 to 64 ready ChatGPT Ads custom audiences into a new audience with replay protection.
Preview ChatGPT Ad#
Creates a shareable ad preview link that expires after 24 hours.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsPreviewAd · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Ad ID | Text | Yes | (empty) | ID of the ad to preview. |
Outputs#
| Output | Type |
|---|---|
| Preview | Object |
Use as an agent tool#
Tool name: openai_ads_preview_ad
MUTATES LIVE ADVERTISING STATE. Create and return a 24-hour shareable ChatGPT ad preview link.
Remove ChatGPT Ads Custom Audience Members#
Removes members from a custom audience. Identifiers are objects with type and value; provide at most 10,000.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsRemoveCustomAudienceMembers · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Custom Audience ID | Text | Yes | (empty) | ID of the custom audience. |
| Identifiers | Object | Yes | — | JSON array of {type, value} identifier objects, with a maximum of 10,000. |
| Expected Revision | Number | No | 0 | Optional audience revision expected before the update. |
Outputs#
| Output | Type |
|---|---|
| Operation | Object |
Use as an agent tool#
Tool name: openai_ads_remove_custom_audience_members
MUTATES LIVE ADVERTISING STATE. Remove 1 to 10,000 inline identifiers from a ChatGPT Ads custom audience with an internally generated idempotency key.
Search ChatGPT Ads Locations#
Searches targetable locations by name, for campaign geo targeting.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsSearchLocations · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Search Query | Text | Yes | (empty) | Location name to search for. |
Outputs#
| Output | Type |
|---|---|
| Locations | List |
| Has More | Yes/No |
| Last Id | Text |
Use as an agent tool#
Tool name: openai_ads_search_locations
Search targetable ChatGPT Ads locations by name. Returns location ids plus type (country/region/dma) and canonical name, for use in campaign targeting.
Send ChatGPT Ads Conversion Events#
Sends 1 to 1,000 conversion events. The customer’s Conversions API key is sensitive and must never be logged. validate_only defaults to false; use true for a safe first run.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsSendConversionEvents · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Conversions API Key | Text | Yes | (empty) | Customer’s sensitive Conversions API key. Never log this value. |
| Pixel ID | Text | Yes | (empty) | ID of the conversion pixel. |
| Events | Object | Yes | — | JSON array of 1 to 1,000 conversion events. |
| Validate Only | Yes/No | No | Off | Validate without sending events. Defaults to false; use true for a safe first run. |
| Integration Source | Text | No | (empty) | Source integration reporting the events. |
Outputs#
| Output | Type |
|---|---|
| Response | Object |
Use as an agent tool#
Tool name: openai_ads_send_conversion_events
MUTATES LIVE ADVERTISING STATE. Send 1 to 1,000 server-side conversion events. The Conversions API key is sensitive and must never be logged. Use validate_only=true for a safe first run; the default is false.
Set ChatGPT Ads Ad Group Status#
Activates, pauses or archives a ChatGPT Ads ad group.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsSetAdGroupStatus · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Ad Group ID | Text | Yes | (empty) | The ad group to transition. |
| Status | Text | Yes | paused | Target state: active, paused or archived. |
Outputs#
| Output | Type |
|---|---|
| Ad Group | Object |
Use as an agent tool#
Tool name: openai_ads_set_ad_group_status
MUTATES LIVE ADVERTISING STATE. Activate, pause or archive a ChatGPT Ads ad group.
Set ChatGPT Ad Status#
Activates, pauses or archives a ChatGPT ad.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsSetAdStatus · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Ad ID | Text | Yes | (empty) | The ad to transition. |
| Status | Text | Yes | paused | Target state: active, paused or archived. |
Outputs#
| Output | Type |
|---|---|
| Ad | Object |
Use as an agent tool#
Tool name: openai_ads_set_ad_status
MUTATES LIVE ADVERTISING STATE. Activate, pause or archive a ChatGPT ad. This is how you stop an underperforming creative from spending.
Set ChatGPT Ads Campaign Status#
Activates, pauses or archives a ChatGPT Ads campaign.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsSetCampaignStatus · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Campaign ID | Text | Yes | (empty) | The campaign to transition. |
| Status | Text | Yes | paused | Target state: active, paused or archived. |
Outputs#
| Output | Type |
|---|---|
| Campaign | Object |
Use as an agent tool#
Tool name: openai_ads_set_campaign_status
MUTATES LIVE ADVERTISING STATE. Activate, pause or archive a ChatGPT Ads campaign. Pausing stops its spend immediately.
Submit ChatGPT Ads Bulk Job#
Submits up to 1000 create/update operations as one job. Prefer a dry run first.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsSubmitBulkJob · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Operations | Object | Yes | — | JSON array of 1-1000 operations, each with operation_id, type (campaign.create, campaign.update, ad_group.create, ad_group.update, ad.create, ad.update), input, plus idempotency_key on creates or target_resource_id on updates. |
| Partial Failure | Yes/No | No | On | Apply the operations that pass instead of discarding the whole job. |
Outputs#
| Output | Type |
|---|---|
| Job | Object |
Use as an agent tool#
Tool name: openai_ads_submit_bulk_job
MUTATES LIVE ADVERTISING STATE. Submit up to 1000 ChatGPT Ads create/update operations as one job. Every job applies immediately — there is no dry run, because the API’s validate_only only checks each operation’s shape, not that its target exists. Poll with openai_ads_get_bulk_job and read outcomes with openai_ads_list_bulk_job_operations.
Update ChatGPT Ad#
Updates a ChatGPT ad. Changing the creative sends it back to review.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsUpdateAd · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Ad ID | Text | Yes | (empty) | The ad to update. |
| Name | Text | No | (empty) | New internal ad name (3-1000 characters). |
| Creative | Object | No | — | Replacement creative, sent WHOLE: {“type”:“chat_card”,“title”:…,“body”:…,“target_url”:…,“file_id”:…}. A partial creative is rejected (“Missing required parameter: creative.type”), and file_id is required unless the campaign is product_feed. Read the ad first to reuse its current file_id, or upload a new image with openai_ads_upload_file. Changing this returns the ad to review. |
Outputs#
| Output | Type |
|---|---|
| Ad | Object |
Use as an agent tool#
Tool name: openai_ads_update_ad
MUTATES LIVE ADVERTISING STATE. Update a ChatGPT ad. Changing a creative sends the ad back to review, so it stops serving until re-approved.
Update ChatGPT Ads Ad Group#
Updates a ChatGPT Ads ad group. Only the fields you supply change.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsUpdateAdGroup · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Ad Group ID | Text | Yes | (empty) | The ad group to update. |
| Name | Text | No | (empty) | New ad group name (3-1000 characters). |
| Description | Text | No | (empty) | New internal notes. |
| Context Hints | Object | No | — | Replacement targeting intent phrases (up to 2000). |
| Bidding Config | Object | No | — | Both fields together: {“billing_event_type”: “click”|“impression”, “max_bid_micros”: n}. The API rejects either on its own, and rejects a flat max_bid_micros (that shape belongs to bulk jobs only). |
| Product Set | Object | No | — | e.g. {“product_feed_id”:“product_feed_123”,“filters”:[{“field”:“brand”,“operator”:“in”,“values”:[“Acme”]},{“field”:“star_rating”,“operator”:“gte”,“values”:[“4.5”]}]}. Fields: title, body, item_id, offer_id, price, target_url, image_url, product_category, brand, seller_name, external_seller_id, star_rating, condition, age_group. Operators: in, or gt/gte/lt/lte on price and star_rating only. One filter per field; values are always strings. The feed id is the campaign’s own, as shown in Ads Manager under Feeds. |
Outputs#
| Output | Type |
|---|---|
| Ad Group | Object |
Use as an agent tool#
Tool name: openai_ads_update_ad_group
MUTATES LIVE ADVERTISING STATE. Update a ChatGPT Ads ad group. Only the supplied fields change.
Update ChatGPT Ads Brand#
Updates the ad account’s display name and/or favicon.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsUpdateBrand · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Name | Text | No | (empty) | New account display name. |
| Favicon File ID | Text | No | (empty) | file_id from an upload with purpose=account_favicon. |
Outputs#
| Output | Type |
|---|---|
| Ad Account | Object |
Use as an agent tool#
Tool name: openai_ads_update_brand
MUTATES LIVE ADVERTISING STATE. Update the ChatGPT ad account’s display name and/or favicon. Supply at least one of them.
Update ChatGPT Ads Campaign#
Updates a ChatGPT Ads campaign. Only the fields you supply change.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsUpdateCampaign · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Campaign ID | Text | Yes | (empty) | The campaign to update. |
| Name | Text | No | (empty) | New campaign name (3-1000 characters). |
| Description | Text | No | (empty) | New internal notes. |
| Budget | Object | No | — | Either {“lifetime_spend_limit_micros”: n} or {“daily_spend_limit_micros”: n} — the API rejects both together. Daily minimum is 25000000 micros, lifetime 1000000. |
| Conversion Event Setting IDs | Object | No | — | Required when bidding type is conversions. |
| Start Time | Number | No | 0 | New scheduled start, as Unix seconds. 0 leaves it unchanged. |
| End Time | Number | No | 0 | New scheduled end, as Unix seconds. 0 leaves it unchanged. |
| Targeting | Object | No | — | REPLACES the whole location list, e.g. {“locations”:{“include”:[{“id”:“1000232”}]}}. Sending an empty include clears targeting. Use openai_ads_search_locations to find ids. |
Outputs#
| Output | Type |
|---|---|
| Campaign | Object |
Use as an agent tool#
Tool name: openai_ads_update_campaign
MUTATES LIVE ADVERTISING STATE. Update a ChatGPT Ads campaign. Only the supplied fields change; omitted fields are left as they are.
Update ChatGPT Ads Feed Products#
Updates feed product availability and titles.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsUpdateFeedProducts · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Feed ID | Text | Yes | (empty) | ID of the product feed. |
| Products | Object | Yes | — | JSON array of products to update. |
Outputs#
| Output | Type |
|---|---|
| Response | Object |
Use as an agent tool#
Tool name: openai_ads_update_feed_products
MUTATES LIVE ADVERTISING STATE. Update product availability and title fields in a ChatGPT Ads feed.
Upload ChatGPT Ads Creative#
Uploads a creative image from a URL and returns its file_id for use in an ad.
Plans: Trial, Pro, Premium, Enterprise · Type: OpenAIAdsUploadFile · Beta
Inputs#
| Field | Type | Required | Default | What it does |
|---|---|---|---|---|
| Image URL | Text | Yes | (empty) | Public URL of the image to upload. |
| Purpose | Text | No | (empty) | Set to account_favicon for a brand favicon; leave empty for ad creatives. |
Outputs#
| Output | Type |
|---|---|
| File | Object |
Use as an agent tool#
Tool name: openai_ads_upload_file
MUTATES LIVE ADVERTISING STATE. Upload a creative image from a public URL and return its file_id, for use as creative.file_id when creating a ChatGPT ad. Account favicons need purpose=account_favicon and at least 128x128 pixels.