PilotMCP
Platforms and tools

OpenAI Ads

The 54 tools Pilot MCP serves for OpenAI Ads: 26 read-only, and 28 that write with the €29 plan, taken from the server.

Pilot MCP serves 26 read-only tools for OpenAI Ads, on every plan. With the €29 plan, it also serves 27 that create or change and 1 that delete. Their names start with openai_ads_.

What each entry shows

The name, description and parameters come from the list the server serves to your assistant (tools/list). Descriptions are in English: this is the text your assistant receives. Your assistant never fills in platform credentials: Pilot adds them on each call.

Writing and deleting

Write tools are only served with the €29 plan: your assistant creates, changes, pauses and deletes there, with no access level to pick when you connect. On the free plan, it does not see them. A change that sets an object to deleted or archived counts as a deletion, and a deletion targets one object at a time. Changes apply directly on the ad platform: Pilot reads the object from the platform before and after the write, and logs it in your workspace. See Read and write.

Tool families

Other tools

openai_ads_openai_ads_account_insights

OpenAI Ads: Account Insights · read-only · idempotent

Insights aggregated at account level (impressions, clicks, spend, ctr, cpc, cpm). time_granularity: daily by default.

ParameterTypeRequiredDescription
time_granularitystringnohourly | daily | monthly | none (default daily). With segments: none, daily or monthly only.
aggregation_levelstringnoRow granularity: ad_account | campaign | ad_group | ad. The endpoint sets the SCOPE, this parameter sets the ROW (an account scope can return one row per ad).
includesstring[]noZero rows: zero_impression_items (entities without impressions, NON-segmented request) | zero_impression_products (product report).
override_segment_group_orderstring[]noGrouping order in a segmented request: name the aggregation_level and the segment exactly once each.
limitnumbernoRows per page (1-2000, default 20).
afterstringnoPagination cursor: the last_id of the previous page.
beforestringnoPagination cursor: the first_id of the previous page.
fieldsstring[]noColumns to project. DELIVERY: impressions, clicks, spend, ctr (ratio: 0.04 = 4 %), cpc, cpm, which can be prefixed by the granularity (campaign.spend); spend is in the account currency, never in micros. RESULTS (flat names, full days in the account time zone, 365 days at most): conversions (click + view over the chosen windows), cpa, post_click_cvr (click only), order_created_attributed_sales, order_created_attributed_sales_currency, order_created_roas; null = unavailable, never zero. METADATA: campaign.name, campaign.status, campaign.budget.daily, ad_group.name, ad.title, ad.copy, ad.link, ad.review_status, metadata.readable_time. CANONICAL names in the request, returned FLAT in the response (campaign_name, readable_time).
filtersobject[]noFilter objects { field, operator (IN|GREATER_THAN|LESS_THAN), value }, combined with AND. E.g. { field: "campaign.status", operator: "IN", value: ["active"] }.
sortobject[]noSort objects { field, direction (asc|desc) }, e.g. { field: "spend", direction: "desc" }.
segmentsstring[]noONE breakdown: product | country | device | platform (ios_app, android_app, desktop_web, ios_web, android_web, web, unknown). platform carries delivery only, not conversions; for conversions by country or device, use openai_ads_conversion_insights with breakdown.
time_rangesobject[]noONE range: { type: 'date_range', since: 'YYYY-MM-DD', until: 'YYYY-MM-DD' (inclusive) } in the account time zone, or unix_range { start, end (exclusive) }. Never in the future.
attribution_window_daysnumbernoClick-through window for conversions and sales: 7, 14 or 30 days (default 30). No effect on delivery.
view_through_attribution_window_daysnumbernoView-through window: 0 excludes it, 1 = one day (default 1). Pilot measures click-through only: pass 0 to match its figures, keep the default to match those of Ads Manager.
attribution_time_basisstringnoad_event_time (default: a conversion is counted on the day of the click or view) | conversion_time (on the day of the conversion, with reduced coverage of non-objective events).
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_ad_group_insights

OpenAI Ads: Ad Group Insights · read-only · idempotent

Performance insights for one ad group; same parameters as openai_ads_account_insights.

ParameterTypeRequiredDescription
ad_group_idstringno
time_granularitystringnohourly | daily | monthly | none (default daily). With segments: none, daily or monthly only.
aggregation_levelstringnoRow granularity: ad_account | campaign | ad_group | ad. The endpoint sets the SCOPE, this parameter sets the ROW (an account scope can return one row per ad).
includesstring[]noZero rows: zero_impression_items (entities without impressions, NON-segmented request) | zero_impression_products (product report).
override_segment_group_orderstring[]noGrouping order in a segmented request: name the aggregation_level and the segment exactly once each.
limitnumbernoRows per page (1-2000, default 20).
afterstringnoPagination cursor: the last_id of the previous page.
beforestringnoPagination cursor: the first_id of the previous page.
fieldsstring[]noColumns to project. DELIVERY: impressions, clicks, spend, ctr (ratio: 0.04 = 4 %), cpc, cpm, which can be prefixed by the granularity (campaign.spend); spend is in the account currency, never in micros. RESULTS (flat names, full days in the account time zone, 365 days at most): conversions (click + view over the chosen windows), cpa, post_click_cvr (click only), order_created_attributed_sales, order_created_attributed_sales_currency, order_created_roas; null = unavailable, never zero. METADATA: campaign.name, campaign.status, campaign.budget.daily, ad_group.name, ad.title, ad.copy, ad.link, ad.review_status, metadata.readable_time. CANONICAL names in the request, returned FLAT in the response (campaign_name, readable_time).
filtersobject[]noFilter objects { field, operator (IN|GREATER_THAN|LESS_THAN), value }, combined with AND. E.g. { field: "campaign.status", operator: "IN", value: ["active"] }.
sortobject[]noSort objects { field, direction (asc|desc) }, e.g. { field: "spend", direction: "desc" }.
segmentsstring[]noONE breakdown: product | country | device | platform (ios_app, android_app, desktop_web, ios_web, android_web, web, unknown). platform carries delivery only, not conversions; for conversions by country or device, use openai_ads_conversion_insights with breakdown.
time_rangesobject[]noONE range: { type: 'date_range', since: 'YYYY-MM-DD', until: 'YYYY-MM-DD' (inclusive) } in the account time zone, or unix_range { start, end (exclusive) }. Never in the future.
attribution_window_daysnumbernoClick-through window for conversions and sales: 7, 14 or 30 days (default 30). No effect on delivery.
view_through_attribution_window_daysnumbernoView-through window: 0 excludes it, 1 = one day (default 1). Pilot measures click-through only: pass 0 to match its figures, keep the default to match those of Ads Manager.
attribution_time_basisstringnoad_event_time (default: a conversion is counted on the day of the click or view) | conversion_time (on the day of the conversion, with reduced coverage of non-objective events).
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_ad_insights

OpenAI Ads: Ad Insights · read-only · idempotent

Performance insights for one ad (impressions, clicks, spend per period).

ParameterTypeRequiredDescription
ad_idstringno
time_granularitystringnohourly | daily | monthly | none (default daily). With segments: none, daily or monthly only.
aggregation_levelstringnoRow granularity: ad_account | campaign | ad_group | ad. The endpoint sets the SCOPE, this parameter sets the ROW (an account scope can return one row per ad).
includesstring[]noZero rows: zero_impression_items (entities without impressions, NON-segmented request) | zero_impression_products (product report).
override_segment_group_orderstring[]noGrouping order in a segmented request: name the aggregation_level and the segment exactly once each.
limitnumbernoRows per page (1-2000, default 20).
afterstringnoPagination cursor: the last_id of the previous page.
beforestringnoPagination cursor: the first_id of the previous page.
fieldsstring[]noColumns to project. DELIVERY: impressions, clicks, spend, ctr (ratio: 0.04 = 4 %), cpc, cpm, which can be prefixed by the granularity (campaign.spend); spend is in the account currency, never in micros. RESULTS (flat names, full days in the account time zone, 365 days at most): conversions (click + view over the chosen windows), cpa, post_click_cvr (click only), order_created_attributed_sales, order_created_attributed_sales_currency, order_created_roas; null = unavailable, never zero. METADATA: campaign.name, campaign.status, campaign.budget.daily, ad_group.name, ad.title, ad.copy, ad.link, ad.review_status, metadata.readable_time. CANONICAL names in the request, returned FLAT in the response (campaign_name, readable_time).
filtersobject[]noFilter objects { field, operator (IN|GREATER_THAN|LESS_THAN), value }, combined with AND. E.g. { field: "campaign.status", operator: "IN", value: ["active"] }.
sortobject[]noSort objects { field, direction (asc|desc) }, e.g. { field: "spend", direction: "desc" }.
segmentsstring[]noONE breakdown: product | country | device | platform (ios_app, android_app, desktop_web, ios_web, android_web, web, unknown). platform carries delivery only, not conversions; for conversions by country or device, use openai_ads_conversion_insights with breakdown.
time_rangesobject[]noONE range: { type: 'date_range', since: 'YYYY-MM-DD', until: 'YYYY-MM-DD' (inclusive) } in the account time zone, or unix_range { start, end (exclusive) }. Never in the future.
attribution_window_daysnumbernoClick-through window for conversions and sales: 7, 14 or 30 days (default 30). No effect on delivery.
view_through_attribution_window_daysnumbernoView-through window: 0 excludes it, 1 = one day (default 1). Pilot measures click-through only: pass 0 to match its figures, keep the default to match those of Ads Manager.
attribution_time_basisstringnoad_event_time (default: a conversion is counted on the day of the click or view) | conversion_time (on the day of the conversion, with reduced coverage of non-objective events).
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_campaign_insights

OpenAI Ads: Campaign Insights · read-only · idempotent

Performance insights for one campaign; same parameters as openai_ads_account_insights.

ParameterTypeRequiredDescription
campaign_idstringno
time_granularitystringnohourly | daily | monthly | none (default daily). With segments: none, daily or monthly only.
aggregation_levelstringnoRow granularity: ad_account | campaign | ad_group | ad. The endpoint sets the SCOPE, this parameter sets the ROW (an account scope can return one row per ad).
includesstring[]noZero rows: zero_impression_items (entities without impressions, NON-segmented request) | zero_impression_products (product report).
override_segment_group_orderstring[]noGrouping order in a segmented request: name the aggregation_level and the segment exactly once each.
limitnumbernoRows per page (1-2000, default 20).
afterstringnoPagination cursor: the last_id of the previous page.
beforestringnoPagination cursor: the first_id of the previous page.
fieldsstring[]noColumns to project. DELIVERY: impressions, clicks, spend, ctr (ratio: 0.04 = 4 %), cpc, cpm, which can be prefixed by the granularity (campaign.spend); spend is in the account currency, never in micros. RESULTS (flat names, full days in the account time zone, 365 days at most): conversions (click + view over the chosen windows), cpa, post_click_cvr (click only), order_created_attributed_sales, order_created_attributed_sales_currency, order_created_roas; null = unavailable, never zero. METADATA: campaign.name, campaign.status, campaign.budget.daily, ad_group.name, ad.title, ad.copy, ad.link, ad.review_status, metadata.readable_time. CANONICAL names in the request, returned FLAT in the response (campaign_name, readable_time).
filtersobject[]noFilter objects { field, operator (IN|GREATER_THAN|LESS_THAN), value }, combined with AND. E.g. { field: "campaign.status", operator: "IN", value: ["active"] }.
sortobject[]noSort objects { field, direction (asc|desc) }, e.g. { field: "spend", direction: "desc" }.
segmentsstring[]noONE breakdown: product | country | device | platform (ios_app, android_app, desktop_web, ios_web, android_web, web, unknown). platform carries delivery only, not conversions; for conversions by country or device, use openai_ads_conversion_insights with breakdown.
time_rangesobject[]noONE range: { type: 'date_range', since: 'YYYY-MM-DD', until: 'YYYY-MM-DD' (inclusive) } in the account time zone, or unix_range { start, end (exclusive) }. Never in the future.
attribution_window_daysnumbernoClick-through window for conversions and sales: 7, 14 or 30 days (default 30). No effect on delivery.
view_through_attribution_window_daysnumbernoView-through window: 0 excludes it, 1 = one day (default 1). Pilot measures click-through only: pass 0 to match its figures, keep the default to match those of Ads Manager.
attribution_time_basisstringnoad_event_time (default: a conversion is counted on the day of the click or view) | conversion_time (on the day of the conversion, with reduced coverage of non-objective events).
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_conversion_insights

OpenAI Ads: Conversion Insights · read-only · idempotent

Attributed objective conversions, per entity and per day (POST, but a READ). REQUIRED: aggregation_level (campaign | ad_group | ad, never ad_account) and time_ranges (ONE range as a JSON string, full days in the account time zone, 365 days at most). entity_ids is required if group_by_entity (default true); false aggregates the account. Returns conversions (click + view over the chosen windows), click_through_conversions, view_through_conversions and order_created_attributed_sales (purchase value, a string, null if unavailable). include: ['attributed_events'] adds the detail per event type (campaign objective or not), filterable by event_names. Pilot measures click-through only: view_through_attribution_window_days = 0. Beyond 2,000 rows (entities × days, or event rows): 413 with no partial result; split the entities or the range.

ParameterTypeRequiredDescription
aggregation_levelstringnocampaign | ad_group | ad.
time_rangesobject[]noRequired: a single range.
time_granularitystringnonone (default) | daily.
breakdownstringnodevice | country.
entity_idsstring[]no
group_by_entitybooleanno
include_zero_rowsbooleannoDefault true; false drops the rows with neither conversions nor sales.
includestring[]no['attributed_events']: detail per event type.
event_namesstring[]noExact event names (requires include): order_created, lead_created, registration_completed...
attribution_window_daysnumberno7 | 14 | 30 (default 30).
view_through_attribution_window_daysnumberno0 | 1 (default 1).
attribution_time_basisstringnoad_event_time (default) | conversion_time.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

OpenAI Ads: Geo Lookup Search · read-only · idempotent

Searches targetable locations (country, region, dma) by term. Returns { id, type, name, country_code, region_code } objects to use in targeting.locations.include.

ParameterTypeRequiredDescription
qstringnoSearch term (e.g. "San Francisco", "France").
limitnumbernoMaximum number of results.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_get_ad

OpenAI Ads: Get Ad · read-only · idempotent

Gets an ad by id: review_status (in_review | approved | rejected) and review. include: ['serving_issues'] for what blocks its delivery. An active, approved ad does not serve if its ad group or campaign is paused.

ParameterTypeRequiredDescription
ad_idstringno
includestring[]no['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_get_ad_account

OpenAI Ads: Get Ad Account · read-only · idempotent

Gets the current Ads account: act_* id, name, currency, time zone, status, review (brand review: status, reason) and account_integrity_review when it exists. Call it first: an 'active' account can still be waiting for a review, and nothing serves before the brand is approved.

ParameterTypeRequiredDescription
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_get_ad_group

OpenAI Ads: Get Ad Group · read-only · idempotent

Gets an ad group by id. include: ['serving_issues', 'bid_too_low']: bid_too_low = the bid is probably too low for regular delivery (advice, not a blocker; never raised on an inactive group nor within 24 h after the group is changed).

ParameterTypeRequiredDescription
ad_group_idstringno
includestring[]noserving_issues | bid_too_low.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_get_campaign

OpenAI Ads: Get Campaign · read-only · idempotent

Gets a campaign by id. include: ['serving_issues'] tells what blocks its delivery (budget, schedule, targeting, review).

ParameterTypeRequiredDescription
campaign_idstringno
includestring[]no['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_get_custom_audience

OpenAI Ads: Get Custom Audience · read-only · idempotent

Gets an audience by id (including its matched volume).

ParameterTypeRequiredDescription
custom_audience_idstringno
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_get_custom_audience_operation

OpenAI Ads: Get Custom Audience Operation · read-only · idempotent

Reads the state of an audience operation (add / remove / replace / merge), to follow it until it completes.

ParameterTypeRequiredDescription
custom_audience_idstringno
operation_idstringno
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_get_feed_settings

OpenAI Ads: Get Feed Settings · read-only · idempotent

Gets the settings of one product feed (feed_id): display name and organic-listing setting.

ParameterTypeRequiredDescription
feed_idstringno
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_get_landing_page_crawl

OpenAI Ads: Get Landing Page Crawl · read-only · idempotent

Proof that the crawler visited the landing page of the submitted version of an ad: the capture status and, when it exists, a screenshot valid for 24 h. Read it when an ad is rejected or does not serve, to check that the page opens. 404 = no capture, 409 = capture in progress. It starts no crawl.

ParameterTypeRequiredDescription
ad_idstringno
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_ad_groups

OpenAI Ads: List Ad Groups · read-only · idempotent

Lists the account's ad groups, filterable by campaign: bidding_config, context_hints, product_set. include: ['serving_issues'] for delivery blockers.

ParameterTypeRequiredDescription
campaign_idstringnoParent campaign (optional).
namestringnoFilter on the name.
includestring[]no['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions.
limitnumbernoPage size (1-500, default 20).
afterstringnoPagination cursor (the id to start after).
beforestringnoPagination cursor (the id to end before).
orderstringnoasc | desc.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_ads

OpenAI Ads: List Ads · read-only · idempotent

Lists the account's ads, filterable by ad group: creative, review_status. include: ['serving_issues'] for delivery blockers.

ParameterTypeRequiredDescription
ad_group_idstringnoParent ad group (optional).
namestringnoFilter on the name.
includestring[]no['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions.
limitnumbernoPage size (1-500, default 20).
afterstringnoPagination cursor (the id to start after).
beforestringnoPagination cursor (the id to end before).
orderstringnoasc | desc.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_campaigns

OpenAI Ads: List Campaigns · read-only · idempotent

Lists the account's campaigns: status, bidding_type, budget (micros), targeting, conversion_event_setting_ids. include: ['serving_issues'] for delivery blockers.

ParameterTypeRequiredDescription
namestringnoFilter on the name.
includestring[]no['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions.
limitnumbernoPage size (1-500, default 20).
afterstringnoPagination cursor (the id to start after).
beforestringnoPagination cursor (the id to end before).
orderstringnoasc | desc.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_conversion_event_settings

OpenAI Ads: List Conversion Event Settings · read-only · idempotent

Lists the conversion event settings (what counts as a conversion, and over which attribution window).

ParameterTypeRequiredDescription
limitnumbernoPage size (1-500, default 20).
afterstringnoPagination cursor (the id to start after).
beforestringnoPagination cursor (the id to end before).
orderstringnoasc | desc.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_conversion_events

OpenAI Ads: List Conversion Events · read-only · idempotent

Lists the conversion events received; use it to check that the pixel actually sends something before blaming the targeting.

ParameterTypeRequiredDescription
pidstringnoIdentifier of the data source.
limitnumberno
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_conversion_pixels

OpenAI Ads: List Conversion Pixels · read-only · idempotent

Lists the account's conversion pixels (web data sources).

ParameterTypeRequiredDescription
limitnumbernoPage size (1-500, default 20).
afterstringnoPagination cursor (the id to start after).
beforestringnoPagination cursor (the id to end before).
orderstringnoasc | desc.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_custom_audience_operations

OpenAI Ads: List Custom Audience Operations · read-only · idempotent

Lists the operations of an audience (add, remove, replace, merge) and their state.

ParameterTypeRequiredDescription
custom_audience_idstringno
limitnumbernoPage size (1-500, default 20).
afterstringnoPagination cursor (the id to start after).
beforestringnoPagination cursor (the id to end before).
orderstringnoasc | desc.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_custom_audiences

OpenAI Ads: List Custom Audiences · read-only · idempotent

Lists the custom audiences. intended_use: inclusion | exclusion | bid_multiplier.

ParameterTypeRequiredDescription
intended_usestringnoinclusion | exclusion | bid_multiplier.
custom_audience_idsstring[]no
matched_count_granularitystringno
limitnumbernoPage size (1-500, default 20).
afterstringnoPagination cursor (the id to start after).
beforestringnoPagination cursor (the id to end before).
orderstringnoasc | desc.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_feeds

OpenAI Ads: List Feeds · read-only · idempotent

Lists the account's product feeds (open beta).

ParameterTypeRequiredDescription
limitnumbernoPage size (1-500, default 20).
afterstringnoPagination cursor (the id to start after).
beforestringnoPagination cursor (the id to end before).
orderstringnoasc | desc.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_list_spend_limit_windows

OpenAI Ads: List Spend Limit Windows · read-only · idempotent

Lists the account's spend limit windows: the budget safeguard above the campaign budgets.

ParameterTypeRequiredDescription
limitnumbernoPage size (1-500, default 20).
afterstringnoPagination cursor (the id to start after).
beforestringnoPagination cursor (the id to end before).
orderstringnoasc | desc.
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_preview_ad

OpenAI Ads: Preview Ad · read-only · idempotent

Renders a preview (temporary iframe) of an existing ad: it lets you SHOW the creative before activating it, rather than describe it.

ParameterTypeRequiredDescription
ad_idstringno
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

openai_ads_openai_ads_query_feed_products

OpenAI Ads: Query Feed Products · read-only · idempotent

Queries the items of a feed (filters, pagination); use it to check what the product campaign will actually serve.

ParameterTypeRequiredDescription
feed_idstringno
filtersobject[]no
limitnumberno
afterstringno
account_idstringnoOpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace.

Create and change (€29)

Served with the €29 plan.

openai_ads_openai_ads_activate_ad

OpenAI Ads: Activate Ad · create or change, €29 plan · creates an object on each call

Activates an ad so that it can serve (POST /ads/{ad_id}/activate).

ParameterTypeRequiredDescription
ad_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_activate_ad_account

OpenAI Ads: Activate Ad Account · create or change, €29 plan · creates an object on each call

Activates the ad account (POST /ad_account/activate).

ParameterTypeRequiredDescription
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_activate_ad_group

OpenAI Ads: Activate Ad Group · create or change, €29 plan · creates an object on each call

Activates an ad group so that it can serve (POST /ad_groups/{ad_group_id}/activate).

ParameterTypeRequiredDescription
ad_group_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_activate_campaign

OpenAI Ads: Activate Campaign · create or change, €29 plan · creates an object on each call

Activates a campaign. Returns the updated campaign.

ParameterTypeRequiredDescription
campaign_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_archive_ad

OpenAI Ads: Archive Ad · create or change, €29 plan · creates an object on each call

Archives an ad (POST /ads/{ad_id}/archive).

ParameterTypeRequiredDescription
ad_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_archive_ad_group

OpenAI Ads: Archive Ad Group · create or change, €29 plan · creates an object on each call

Archives an ad group (POST /ad_groups/{ad_group_id}/archive).

ParameterTypeRequiredDescription
ad_group_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_archive_campaign

OpenAI Ads: Archive Campaign · create or change, €29 plan · creates an object on each call

Archives a campaign. Returns the updated campaign.

ParameterTypeRequiredDescription
campaign_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_archive_custom_audience

OpenAI Ads: Archive Custom Audience · create or change, €29 plan · creates an object on each call

Archives a custom audience (POST /custom_audiences/{custom_audience_id}/archive).

ParameterTypeRequiredDescription
custom_audience_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_archive_feed

OpenAI Ads: Archive Feed · create or change, €29 plan · creates an object on each call

Archives a product feed (POST /feeds/{feed_id}/archive).

ParameterTypeRequiredDescription
feed_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_create_ad

OpenAI Ads: Create Ad · create or change, €29 plan · creates an object on each call

Creates an ad. TWO creative types: 'chat_card' (conversation card: title 3-50 chars, body max 100 chars, target_url, file_id from upload) and 'product_ad_template' (product ad: inherits the image and URL of the feed item, requires a campaign with mode=product_feed).

ParameterTypeRequiredDescription
ad_group_idstringno
namestringno3-1000 characters.
statusstringnoactive | paused.
creativeobjectno{ type: 'chat_card'|'product_ad_template', title, body, price?, target_url?, file_id?, image_crop? }.
landing_page_configurationobjectno{ query_string_template }.
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_create_ad_group

OpenAI Ads: Create Ad Group · create or change, €29 plan · creates an object on each call

Creates an ad group. bidding_config REQUIRED: { billing_event_type: 'impression'|'click', strategy: 'fixed_bid'|'maximize_clicks'|'maximize_conversions', max_bid_micros (fixed_bid only) }. Maximize: a campaign with a daily budget, billing 'click', no max_bid_micros and no audience multipliers. On a conversions campaign with fixed_bid, max_bid_micros is the CPA bid (billing stays per click). With impressions, the bid is PER impression: a CPM of 60 = 60000 micros. context_hints: sentences that describe the offer and its uses ('lightweight trail shoes for rocky terrain'), not exact keywords; 2,000 at most.

ParameterTypeRequiredDescription
campaign_idstringno
namestringno3-1000 characters.
statusstringnoactive | paused.
bidding_configobjectno{ billing_event_type: 'impression'|'click', strategy?, max_bid_micros?, custom_audience_bid_multipliers?: [{ custom_audience_id, bid_multiplier_micros }] (0.1x to 10x, in micros: 1500000 = 1.5x) }.
context_hintsstring[]noContext sentences (e.g. ["Scheduling software for teams of 10 to 50 people"]).
product_setobjectno{ product_feed_id, filters? }: restricts an ad group to a subset of the product feed.
landing_page_configurationobjectno{ query_string_template }.
descriptionstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_create_campaign

OpenAI Ads: Create Campaign · create or change, €29 plan · creates an object on each call

Creates a campaign. budget: ONLY ONE of daily_spend_limit_micros (required by the Maximize strategies) or lifetime_spend_limit_micros, in micros (25 USD = 25000000, minimum 1000000; the daily minimum depends on the currency). A daily budget never becomes a lifetime budget again. status: active | paused. bidding_type: impressions | clicks | conversions; 'conversions' requires conversion_event_setting_ids and the Conversions surface enabled on the account.

ParameterTypeRequiredDescription
namestringno3-1000 characters.
statusstringnoactive | paused.
budgetobjectno{ lifetime_spend_limit_micros: number (required), daily_spend_limit_micros?: number }.
bidding_typestringnoimpressions | clicks | conversions.
objectivestringnoreach | clicks | conversions.
billing_event_typestringnoimpression | click. There is NO billing per conversion: a conversions campaign is paid per CLICK (oCPC).
modestringnoproduct_feed | business_agent.
product_feed_idstringnoRequired if mode=product_feed.
business_agent_idstringnoRequired if mode=business_agent.
conversion_event_setting_idsstring[]noRequired if bidding_type=conversions.
descriptionstringno
start_timenumbernoUnix seconds.
end_timenumbernoUnix seconds.
targetingobjectno{ locations: { countries: ['FR'] } or { include: [{id}] }, excluded_locations: { countries } or { include: [{id}] }, custom_audiences: { ids: [] }, excluded_custom_audiences: { ids: [] }, platforms: { included: ['web'|'ios_app'|'android_app'] } }. Without platforms: all surfaces. A geography or audience update REPLACES the previous one: send the full configuration again.
landing_page_configurationobjectno{ query_string_template }: tracking parameters (UTM) added to the destination URL.
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_create_conversion_event_setting

OpenAI Ads: Create Conversion Event Setting · create or change, €29 plan · creates an object on each call

Creates a conversion event setting. Required: name, event_type, attribution_window_days, source_ids (the pixels). Its id is used as conversion_event_setting_ids on a campaign with bidding_type=conversions. The API cannot change or delete an event setting afterwards (only create and list).

ParameterTypeRequiredDescription
namestringno
event_typestringnoStandard event type, or 'custom' with custom_event_name.
custom_event_namestringno
attribution_window_daysnumbernoClick-through attribution window, in days.
source_idsstring[]noIDs of the pixels / data sources.
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_create_conversion_pixel

OpenAI Ads: Create Conversion Pixel · create or change, €29 plan · creates an object on each call

Creates a conversion pixel. client_type: 'web' (the only value accepted today). Returns the source id to use in an event setting. The API cannot rename or delete a pixel afterwards (only create and list).

ParameterTypeRequiredDescription
namestringno
client_typestringnoweb.
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_create_custom_audience

OpenAI Ads: Create Custom Audience · create or change, €29 plan · creates an object on each call

Creates an audience from an uploaded customer file, or an EMPTY one if no file field is passed. identifier_type: email | phone | email_sha256 | phone_number_sha256 | gaid. This is the platform's ONLY behavioral targeting: there is neither demographic nor interest targeting.

ParameterTypeRequiredDescription
namestringno
descriptionstringno
file_idstringno
identifier_typestringnoemail | phone | email_sha256 | phone_number_sha256 | gaid.
identifier_resolutionstringnoauto.
filenamestringno
mimetypestringno
file_sizenumberno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_create_feed

OpenAI Ads: Create Feed · create or change, €29 plan · creates an object on each call

Creates a product feed. countries = the ISO country codes the feed serves.

ParameterTypeRequiredDescription
namestringno
countriesstring[]no
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_create_spend_limit_window

OpenAI Ads: Create Spend Limit Window · create or change, €29 plan · creates an object on each call

Creates a spend limit window. start_date INCLUSIVE, end_date EXCLUSIVE (YYYY-MM-DD format). amount_micros in micros.

ParameterTypeRequiredDescription
start_datestringnoYYYY-MM-DD, inclusive.
end_datestringnoYYYY-MM-DD, EXCLUSIVE.
amount_microsnumberno
namestringno
io_idstringnoPurchase order reference (insertion order).
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_pause_ad

OpenAI Ads: Pause Ad · create or change, €29 plan · creates an object on each call

Pauses an ad so that it stops serving (POST /ads/{ad_id}/pause).

ParameterTypeRequiredDescription
ad_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_pause_ad_account

OpenAI Ads: Pause Ad Account · create or change, €29 plan · creates an object on each call

Pauses the ENTIRE ad account: all delivery stops. Offer it only on an explicit request.

ParameterTypeRequiredDescription
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_pause_ad_group

OpenAI Ads: Pause Ad Group · create or change, €29 plan · creates an object on each call

Pauses an ad group so that it stops serving (POST /ad_groups/{ad_group_id}/pause).

ParameterTypeRequiredDescription
ad_group_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_pause_campaign

OpenAI Ads: Pause Campaign · create or change, €29 plan · creates an object on each call

Pauses a campaign. Returns the updated campaign.

ParameterTypeRequiredDescription
campaign_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_set_brand

OpenAI Ads: Set Brand · create or change, €29 plan · creates an object on each call

Sets the account brand (display name, icon) and TRIGGERS the brand review. An account serves NOTHING until review.status is 'approved': this is the number one cause of an active campaign without impressions. Then read openai_ads_get_ad_account again until approval; if 'rejected', review.reason says what to fix.

ParameterTypeRequiredDescription
namestringnoDisplay name of the account.
favicon_file_idstringnofile_id of an image uploaded with purpose=account_favicon.
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_update_ad

OpenAI Ads: Update Ad · create or change, €29 plan · creates an object on each call

Updates an ad (POST). Include the full creative object if it changes.

ParameterTypeRequiredDescription
ad_idstringno
namestringno
statusstringno
creativeobjectno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_update_ad_group

OpenAI Ads: Update Ad Group · create or change, €29 plan · creates an object on each call

Updates an ad group (POST). Pass the full bidding_config if it is included. context_hints REPLACES the whole list: read the group, add, send everything back. description can be null to clear it.

ParameterTypeRequiredDescription
ad_group_idstringno
namestringno
statusstringno
bidding_configobjectno
context_hintsstring[]no
descriptionstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_update_campaign

OpenAI Ads: Update Campaign · create or change, €29 plan · creates an object on each call

Updates a campaign (POST, not PATCH). All fields are optional; pass the full budget object if it is included.

ParameterTypeRequiredDescription
campaign_idstringno
namestringno
statusstringno
budgetobjectno
descriptionstringno
start_timenumberno
end_timenumberno
targetingobjectno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_update_feed_settings

OpenAI Ads: Update Feed Settings · create or change, €29 plan · creates an object on each call

Updates the settings of one product feed (feed_id): name (display name) and is_search_eligible_respected (organic listing). Archive a feed with openai_ads_archive_feed.

ParameterTypeRequiredDescription
feed_idstringno
namestringno
is_search_eligible_respectedbooleanno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

openai_ads_openai_ads_upload_image

OpenAI Ads: Upload Image · create or change, €29 plan · creates an object on each call

Uploads an image from a remote URL and returns { file_id }. Without `purpose`, the image is a creative visual (creative.file_id). With `purpose: 'account_favicon'`, it is the brand icon of the ACCOUNT (minimum 128x128); passing the SITE URL is then enough, the API extracts an icon from it. (For a local file, the endpoint also accepts multipart/form-data.) The API has no operation to read, change or delete an uploaded file: it stays in the account.

ParameterTypeRequiredDescription
image_urlstringnoPublic URL of the image, or the site URL when purpose=account_favicon.
purposestringnoaccount_favicon for a brand icon; omit it for a creative visual.
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

Delete (€29)

Served with the €29 plan. A deletion targets one object at a time.

openai_ads_openai_ads_delete_spend_limit_window

OpenAI Ads: Delete Spend Limit Window · delete, €29 plan, one object at a time · creates an object on each call

Deletes one of the account's spend limit windows, by window_id.

ParameterTypeRequiredDescription
window_idstringno
account_idstringnoOpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account.

On this page