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
| Family | Tools |
|---|---|
| Other tools | 26 |
| Create and change (€29) | 27 |
| Delete (€29) | 1 |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
time_granularity | string | no | hourly | daily | monthly | none (default daily). With segments: none, daily or monthly only. |
aggregation_level | string | no | Row 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). |
includes | string[] | no | Zero rows: zero_impression_items (entities without impressions, NON-segmented request) | zero_impression_products (product report). |
override_segment_group_order | string[] | no | Grouping order in a segmented request: name the aggregation_level and the segment exactly once each. |
limit | number | no | Rows per page (1-2000, default 20). |
after | string | no | Pagination cursor: the last_id of the previous page. |
before | string | no | Pagination cursor: the first_id of the previous page. |
fields | string[] | no | Columns 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). |
filters | object[] | no | Filter objects { field, operator (IN|GREATER_THAN|LESS_THAN), value }, combined with AND. E.g. { field: "campaign.status", operator: "IN", value: ["active"] }. |
sort | object[] | no | Sort objects { field, direction (asc|desc) }, e.g. { field: "spend", direction: "desc" }. |
segments | string[] | no | ONE 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_ranges | object[] | no | ONE 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_days | number | no | Click-through window for conversions and sales: 7, 14 or 30 days (default 30). No effect on delivery. |
view_through_attribution_window_days | number | no | View-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_basis | string | no | ad_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_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_group_id | string | no | |
time_granularity | string | no | hourly | daily | monthly | none (default daily). With segments: none, daily or monthly only. |
aggregation_level | string | no | Row 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). |
includes | string[] | no | Zero rows: zero_impression_items (entities without impressions, NON-segmented request) | zero_impression_products (product report). |
override_segment_group_order | string[] | no | Grouping order in a segmented request: name the aggregation_level and the segment exactly once each. |
limit | number | no | Rows per page (1-2000, default 20). |
after | string | no | Pagination cursor: the last_id of the previous page. |
before | string | no | Pagination cursor: the first_id of the previous page. |
fields | string[] | no | Columns 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). |
filters | object[] | no | Filter objects { field, operator (IN|GREATER_THAN|LESS_THAN), value }, combined with AND. E.g. { field: "campaign.status", operator: "IN", value: ["active"] }. |
sort | object[] | no | Sort objects { field, direction (asc|desc) }, e.g. { field: "spend", direction: "desc" }. |
segments | string[] | no | ONE 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_ranges | object[] | no | ONE 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_days | number | no | Click-through window for conversions and sales: 7, 14 or 30 days (default 30). No effect on delivery. |
view_through_attribution_window_days | number | no | View-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_basis | string | no | ad_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_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_id | string | no | |
time_granularity | string | no | hourly | daily | monthly | none (default daily). With segments: none, daily or monthly only. |
aggregation_level | string | no | Row 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). |
includes | string[] | no | Zero rows: zero_impression_items (entities without impressions, NON-segmented request) | zero_impression_products (product report). |
override_segment_group_order | string[] | no | Grouping order in a segmented request: name the aggregation_level and the segment exactly once each. |
limit | number | no | Rows per page (1-2000, default 20). |
after | string | no | Pagination cursor: the last_id of the previous page. |
before | string | no | Pagination cursor: the first_id of the previous page. |
fields | string[] | no | Columns 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). |
filters | object[] | no | Filter objects { field, operator (IN|GREATER_THAN|LESS_THAN), value }, combined with AND. E.g. { field: "campaign.status", operator: "IN", value: ["active"] }. |
sort | object[] | no | Sort objects { field, direction (asc|desc) }, e.g. { field: "spend", direction: "desc" }. |
segments | string[] | no | ONE 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_ranges | object[] | no | ONE 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_days | number | no | Click-through window for conversions and sales: 7, 14 or 30 days (default 30). No effect on delivery. |
view_through_attribution_window_days | number | no | View-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_basis | string | no | ad_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_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | |
time_granularity | string | no | hourly | daily | monthly | none (default daily). With segments: none, daily or monthly only. |
aggregation_level | string | no | Row 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). |
includes | string[] | no | Zero rows: zero_impression_items (entities without impressions, NON-segmented request) | zero_impression_products (product report). |
override_segment_group_order | string[] | no | Grouping order in a segmented request: name the aggregation_level and the segment exactly once each. |
limit | number | no | Rows per page (1-2000, default 20). |
after | string | no | Pagination cursor: the last_id of the previous page. |
before | string | no | Pagination cursor: the first_id of the previous page. |
fields | string[] | no | Columns 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). |
filters | object[] | no | Filter objects { field, operator (IN|GREATER_THAN|LESS_THAN), value }, combined with AND. E.g. { field: "campaign.status", operator: "IN", value: ["active"] }. |
sort | object[] | no | Sort objects { field, direction (asc|desc) }, e.g. { field: "spend", direction: "desc" }. |
segments | string[] | no | ONE 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_ranges | object[] | no | ONE 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_days | number | no | Click-through window for conversions and sales: 7, 14 or 30 days (default 30). No effect on delivery. |
view_through_attribution_window_days | number | no | View-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_basis | string | no | ad_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_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
aggregation_level | string | no | campaign | ad_group | ad. |
time_ranges | object[] | no | Required: a single range. |
time_granularity | string | no | none (default) | daily. |
breakdown | string | no | device | country. |
entity_ids | string[] | no | |
group_by_entity | boolean | no | |
include_zero_rows | boolean | no | Default true; false drops the rows with neither conversions nor sales. |
include | string[] | no | ['attributed_events']: detail per event type. |
event_names | string[] | no | Exact event names (requires include): order_created, lead_created, registration_completed... |
attribution_window_days | number | no | 7 | 14 | 30 (default 30). |
view_through_attribution_window_days | number | no | 0 | 1 (default 1). |
attribution_time_basis | string | no | ad_event_time (default) | conversion_time. |
account_id | string | no | OpenAI Ads account to use when the workspace has several. Default: the first account linked to the workspace. |
openai_ads_openai_ads_geo_lookup_search
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | no | Search term (e.g. "San Francisco", "France"). |
limit | number | no | Maximum number of results. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_id | string | no | |
include | string[] | no | ['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_group_id | string | no | |
include | string[] | no | serving_issues | bid_too_low. |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | |
include | string[] | no | ['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions. |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
custom_audience_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
custom_audience_id | string | no | |
operation_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
feed_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | Parent campaign (optional). |
name | string | no | Filter on the name. |
include | string[] | no | ['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions. |
limit | number | no | Page size (1-500, default 20). |
after | string | no | Pagination cursor (the id to start after). |
before | string | no | Pagination cursor (the id to end before). |
order | string | no | asc | desc. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_group_id | string | no | Parent ad group (optional). |
name | string | no | Filter on the name. |
include | string[] | no | ['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions. |
limit | number | no | Page size (1-500, default 20). |
after | string | no | Pagination cursor (the id to start after). |
before | string | no | Pagination cursor (the id to end before). |
order | string | no | asc | desc. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | no | Filter on the name. |
include | string[] | no | ['serving_issues'] adds the serving issues (what blocks delivery) of each resource. An empty array is not a promise of impressions. |
limit | number | no | Page size (1-500, default 20). |
after | string | no | Pagination cursor (the id to start after). |
before | string | no | Pagination cursor (the id to end before). |
order | string | no | asc | desc. |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | no | Page size (1-500, default 20). |
after | string | no | Pagination cursor (the id to start after). |
before | string | no | Pagination cursor (the id to end before). |
order | string | no | asc | desc. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
pid | string | no | Identifier of the data source. |
limit | number | no | |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | no | Page size (1-500, default 20). |
after | string | no | Pagination cursor (the id to start after). |
before | string | no | Pagination cursor (the id to end before). |
order | string | no | asc | desc. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
custom_audience_id | string | no | |
limit | number | no | Page size (1-500, default 20). |
after | string | no | Pagination cursor (the id to start after). |
before | string | no | Pagination cursor (the id to end before). |
order | string | no | asc | desc. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
intended_use | string | no | inclusion | exclusion | bid_multiplier. |
custom_audience_ids | string[] | no | |
matched_count_granularity | string | no | |
limit | number | no | Page size (1-500, default 20). |
after | string | no | Pagination cursor (the id to start after). |
before | string | no | Pagination cursor (the id to end before). |
order | string | no | asc | desc. |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | no | Page size (1-500, default 20). |
after | string | no | Pagination cursor (the id to start after). |
before | string | no | Pagination cursor (the id to end before). |
order | string | no | asc | desc. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | no | Page size (1-500, default 20). |
after | string | no | Pagination cursor (the id to start after). |
before | string | no | Pagination cursor (the id to end before). |
order | string | no | asc | desc. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
feed_id | string | no | |
filters | object[] | no | |
limit | number | no | |
after | string | no | |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_id | string | no | |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_group_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_id | string | no | |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_group_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
custom_audience_id | string | no | |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
feed_id | string | no | |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_group_id | string | no | |
name | string | no | 3-1000 characters. |
status | string | no | active | paused. |
creative | object | no | { type: 'chat_card'|'product_ad_template', title, body, price?, target_url?, file_id?, image_crop? }. |
landing_page_configuration | object | no | { query_string_template }. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | |
name | string | no | 3-1000 characters. |
status | string | no | active | paused. |
bidding_config | object | no | { 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_hints | string[] | no | Context sentences (e.g. ["Scheduling software for teams of 10 to 50 people"]). |
product_set | object | no | { product_feed_id, filters? }: restricts an ad group to a subset of the product feed. |
landing_page_configuration | object | no | { query_string_template }. |
description | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | no | 3-1000 characters. |
status | string | no | active | paused. |
budget | object | no | { lifetime_spend_limit_micros: number (required), daily_spend_limit_micros?: number }. |
bidding_type | string | no | impressions | clicks | conversions. |
objective | string | no | reach | clicks | conversions. |
billing_event_type | string | no | impression | click. There is NO billing per conversion: a conversions campaign is paid per CLICK (oCPC). |
mode | string | no | product_feed | business_agent. |
product_feed_id | string | no | Required if mode=product_feed. |
business_agent_id | string | no | Required if mode=business_agent. |
conversion_event_setting_ids | string[] | no | Required if bidding_type=conversions. |
description | string | no | |
start_time | number | no | Unix seconds. |
end_time | number | no | Unix seconds. |
targeting | object | no | { 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_configuration | object | no | { query_string_template }: tracking parameters (UTM) added to the destination URL. |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | no | |
event_type | string | no | Standard event type, or 'custom' with custom_event_name. |
custom_event_name | string | no | |
attribution_window_days | number | no | Click-through attribution window, in days. |
source_ids | string[] | no | IDs of the pixels / data sources. |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | no | |
client_type | string | no | web. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | no | |
description | string | no | |
file_id | string | no | |
identifier_type | string | no | email | phone | email_sha256 | phone_number_sha256 | gaid. |
identifier_resolution | string | no | auto. |
filename | string | no | |
mimetype | string | no | |
file_size | number | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | no | |
countries | string[] | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | no | YYYY-MM-DD, inclusive. |
end_date | string | no | YYYY-MM-DD, EXCLUSIVE. |
amount_micros | number | no | |
name | string | no | |
io_id | string | no | Purchase order reference (insertion order). |
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
account_id | string | no | OpenAI 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).
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_group_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | no | Display name of the account. |
favicon_file_id | string | no | file_id of an image uploaded with purpose=account_favicon. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_id | string | no | |
name | string | no | |
status | string | no | |
creative | object | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
ad_group_id | string | no | |
name | string | no | |
status | string | no | |
bidding_config | object | no | |
context_hints | string[] | no | |
description | string | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
campaign_id | string | no | |
name | string | no | |
status | string | no | |
budget | object | no | |
description | string | no | |
start_time | number | no | |
end_time | number | no | |
targeting | object | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
feed_id | string | no | |
name | string | no | |
is_search_eligible_respected | boolean | no | |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
image_url | string | no | Public URL of the image, or the site URL when purpose=account_favicon. |
purpose | string | no | account_favicon for a brand icon; omit it for a creative visual. |
account_id | string | no | OpenAI 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
window_id | string | no | |
account_id | string | no | OpenAI Ads account that owns the target object. Required when the workspace has several linked accounts; otherwise its only account. |