OpenAI Ads connector tools

  • Updated

The OpenAI Ads connector tools in Optimizely Opal give you direct access to your OpenAI (ChatGPT) advertising performance data. Use them to retrieve campaign, ad group, and ad-level metrics, then ask Opal to identify wasted spend, model budget scenarios, and flag underperforming creative. This supports data-backed decisions about where to cut, shift, or increase ad spend.

First, an Opal administrator must connect Opal with OpenAI Ads using an OpenAI Ads API key in Optimizely Connect Platform (OCP). After an administrator installs the connector in Optimizely Connect Platform (OCP), you can log in to OpenAI Ads from Opal to access your data. Administrators only need to install the OpenAI Ads connection in OCP once. 

Use cases

The following use cases show how you can use OpenAI Ads connector tools in Opal to turn ad performance data into spend and creative decisions.

Spend and budget optimization

Goal – Identify wasted spend and reallocate budget with confidence.

  • Spend efficiency triage – Use the openai_ads_get_insights and openai_ads_get_conversion_insights tools to pull the last 14 days of performance by campaign and ad group, rank the results by cost per conversion, and flag any ad group where cost per click (CPC) rose while conversions fell.
  • Find stranded budget – Use the openai_ads_list_campaigns and openai_ads_list_ad_groups tools to review status, budget, and bid across your account, then use openai_ads_list_ads and openai_ads_list_conversion_event_settings to find ad groups that are active with no eligible ads or that are spending with no conversion event attached.
  • Budget reallocation plan – Use the openai_ads_get_insights and openai_ads_get_conversion_insights tools to compare spend against conversions across all campaigns over the last 30 days and recommend specific dollar amounts to cut or increase, without applying any changes.

Bid and creative performance

Goal – Correct bidding pressure and cut underperforming creative.

  • Bid pressure check – Use the openai_ads_get_insights tool to show CPC and cost per mille (CPM) trends by ad group over the last 30 days, then use openai_ads_get_ad_group to compare the current bid against conversion value and recommend a corrected maximum bid.
  • Creative cost check – Use the openai_ads_get_insights and openai_ads_get_conversion_insights tools to rank all ads by cost per conversion over 30 days, use openai_ads_get_ad to pull the copy for the top and bottom three ads, and draft replacement variants with openai_ads_create_ad or openai_ads_update_ad.

Audience and geographic targeting

Goal – Refine who and where your ads reach before you scale spend.

  • Geo targeting setup – Use the openai_ads_search_geo tool to resolve city, region, or country names into targetable geo IDs before you build a new campaign or ad group.
  • Audience segment review – Use the openai_ads_list_custom_audiences tool to see which custom audience segments are available, then apply the best-performing segment to a new or existing ad group.

Connect Opal with OpenAI Ads

Install the OpenAI Ads tools in OCP

In the OCP App Directory, complete the following steps: 

  1. Locate or click the OpenAI Ads Tools app.

  2. Click Install App.

Configure OpenAI Ads API authentication

Connect this tool to your OpenAI (Chatgpt) ad account using an OpenAI Ads API key. To get an API key, complete the following steps:

  1. Go to the Settings > OpenAI Ads Authentication.
  2. Enter your OpenAI Ads API key. To get an API key, complete the following steps:
    • Sign in to OpenAI Ads Manager.
    • Open the Settings tab.
    • Generate (or copy) an API key.   

  3. Enter your OpenAI API Key in the configuration field.

  4. Click Save.

Configure tool permissions

  1. Select the Settings tab. 
  2. Expand the Tools Permissions section.
  3. (Optional) Manage write tools:
    • To prevent Opal from executing live changes in your ad account, disable the optional Write tools.
    • To enable automated actions (such as updating bids and budgets), keep write tools enabled.

  4. Click Save.

Add the OpenAI Ads connector tools to Opal

After you install the app in OCP and configure API authentication, complete the following steps to connect the tools to Opal:

  1. Select the Settings tab.
  2. Expand Add to Opal.

  3. Click Add to Opal for the Opal account you want to add the OpenAI Ads connector tools to.

Click Remove from Opal to remove the connection.

The OpenAI Ads connector tools use this account-level API key for authentication. Individual Opal users do not need to connect a personal OpenAI Ads login before using these tools.

OpenAI Ads connector tools

After an Opal administrator installs the Opal OpenAI Ads Tool in OCP and configures API authentication, call the following tools in Opal. Click a tool to expand it and learn when to use it, available parameters, and example prompts. If you do not provide a required parameter, Opal prompts you for it.

Account and campaign management

openai_ads_archive_campaign – Permanently archive a campaign in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Permanently retire a campaign you no longer intend to run (cannot be reactivated).
    • Remove an obsolete or finished campaign from the active set.
    • Retire a campaign when pausing is not enough (stops its ad groups and ads permanently).
  • Parameters
    • campaign_id – The ID of the campaign to archive. Example: "campaign_abc123".
  • Example prompts
    • Archive campaign campaign_abc123 permanently.
    • Retire the "Spring Launch" campaign for good.
    • Close out and archive our finished holiday campaign.
openai_ads_create_campaign – Create a new advertising campaign in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Launch a new advertising initiative in OpenAI Ads Manager.
    • Set up a paused campaign with budget limits (lifetime ceiling and/or average daily) to review before spending.
    • Configure campaign bidding type, flight dates, geo-targeting, and conversion event tracking.
  • Parameters
    • name – Campaign name (3–1000 characters). Example: "Spring Launch".
    • (Optional) lifetime_spend_limit_micros – Total lifetime budget cap in micros (min 1,000,000; hard ceiling on total spend). Provide at least one of lifetime or daily spend limit.
    • (Optional) daily_spend_limit_micros – Average daily budget in micros (min 1,000,000). Note: Spend may reach 2x this on a single day, up to 7x across any 7-day period.
    • (Optional) bidding_type – Bidding type: "impressions" or "clicks".
    • (Optional) status – Initial status: "active" or "paused" (default: "paused").
    • (Optional) start_time – Start time as an ISO date/datetime in UTC (e.g. "2026-06-01").
    • (Optional) end_time – End time as an ISO date/datetime in UTC (e.g. "2026-12-31").
    • (Optional) description – Free-text description of the campaign.
    • (Optional) targeting – Targeting JSON object string (e.g. location inclusions).
    • (Optional) conversion_event_setting_ids – Conversion event setting IDs as a JSON array string.
    • (Optional) mode – Campaign mode: "product_feed" for retail/feed campaigns; omit for standard campaigns.
  • Example prompts
    • Create a new paused campaign called "Spring Launch" with a $50 lifetime budget cap.
    • Set up an always-on campaign with a $10 daily budget bidding on clicks.
    • Launch a campaign scheduled to start on June 1, 2026.
openai_ads_get_ad_account – Get metadata for the OpenAI (ChatGPT) ad account connected to this tool.
  • When to use
    • Confirm which ad account is connected and retrieve its ID, name, status, currency, and timezone.
    • Verify API key configuration and account review status before creating campaigns.
    • Check account-level defaults before setting up budgets.
  • Parameters
    • No parameters required.
  • Example prompts
    • What is our connected OpenAI ad account?
    • Check the status and currency of our ad account.
    • Get our OpenAI Ads account details and timezone.
openai_ads_get_campaign – Get a single OpenAI (ChatGPT) advertising campaign by its ID.
  • When to use
    • Inspect a campaign's full configuration, status, and flight schedule.
    • Check current lifetime budget caps and daily spend limits before making changes.
    • Confirm campaign status before activating, pausing, or updating it.
  • Parameters
    • campaign_id – The ID of the campaign to retrieve. Example: "campaign_abc123".
  • Example prompts
    • Get the configuration of campaign campaign_abc123.
    • What is the budget limit on our Spring Launch campaign?
    • Check if campaign campaign_xyz is currently active or paused.
openai_ads_list_campaigns – List advertising campaigns in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • View all campaigns along with their status, bidding type, and budget limits.
    • Find campaign IDs needed to manage ad groups, ads, or performance reporting.
    • Page through large sets of campaigns using pagination cursors.
  • Parameters
    • (Optional) limit – Maximum number of campaigns to return (default: "25").
    • (Optional) order – Sort order by creation time: "asc" or "desc".
    • (Optional) after – Pagination cursor to return campaigns after this ID.
    • (Optional) before – Pagination cursor to return campaigns before this ID.
  • Example prompts
    • What campaigns do we have in OpenAI Ads?
    • List our active advertising campaigns.
    • Show all campaigns sorted by newest first.
openai_ads_set_campaign_status – Activate or pause a campaign in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Start a paused campaign serving and spending (once its ads pass review).
    • Stop a running campaign immediately without losing its configuration or structure.
    • Quickly toggle campaign spend on or off in response to performance or budget concerns.
  • Parameters
    • campaign_id – The ID of the campaign to transition. Example: "campaign_abc123".
    • action – "activate" (starts serving/spending) or "pause" (stops serving; reversible).
  • Example prompts
    • Activate campaign campaign_abc123 to start spending.
    • Pause our Spring Launch campaign immediately.
    • Resume the paused campaign.
openai_ads_update_campaign – Update an existing campaign in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Raise or lower a campaign's lifetime budget cap or average daily budget.
    • Rename a campaign or update its description, start time, or end time.
    • Change status or replace targeting and conversion event settings.
  • Parameters
    • campaign_id – The ID of the campaign to update. Example: "campaign_abc123".
    • (Optional) name – New campaign name (3–1000 characters).
    • (Optional) status – New status: "active", "paused", or "archived".
    • (Optional) lifetime_spend_limit_micros – New lifetime budget cap in micros (min 1,000,000). Hard ceiling on total spend.
    • (Optional) daily_spend_limit_micros – New average daily budget in micros (min 1,000,000).
    • (Optional) start_time – New start time as an ISO date/datetime in UTC.
    • (Optional) end_time – New end time as an ISO date/datetime in UTC.
    • (Optional) description – New description.
    • (Optional) targeting – Replacement targeting as a JSON object string.
    • (Optional) conversion_event_setting_ids – Replacement conversion event setting IDs as a JSON array string.
  • Example prompts
    • Increase the lifetime budget for campaign campaign_abc123 to $75.
    • Rename our campaign to "Spring Launch (v2)" and pause it.
    • Extend the end date of campaign campaign_123 to December 31, 2026.

Ad group management

openai_ads_archive_ad_group – Permanently archive an ad group in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Permanently retire an ad group so it and its ads stop serving for good (irreversible).
    • Clean up ad groups you are certain you will never run again.
    • Remove obsolete or discontinued ad groups from the account.
  • Parameters
    • ad_group_id – The ID of the ad group to archive. Example: "ad_group_abc123".
  • Example prompts
    • Permanently archive ad group ad_group_abc123.
    • Retire the "Summer Promo" ad group.
    • Archive this ad group and stop all its ads permanently.
openai_ads_create_ad_group – Create a new ad group under a campaign in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Add an ad group container to an existing campaign with a bidding configuration.
    • Set up prospecting or product-feed ad groups with specific max bids and billing event types.
    • Establish targeting hints, custom audience bid multipliers, or product sets.
  • Parameters
    • campaign_id – The parent campaign ID. Example: "campaign_abc123".
    • name – Ad group name (3–1000 characters). Example: "US Prospecting".
    • billing_event_type – What you pay per: "impression" or "click".
    • max_bid_micros – Maximum bid in micros (1,000,000 micros = 1 currency unit). Example: "500000" = 0.50 units.
    • (Optional) status – Initial status: "active" or "paused" (default: "paused").
    • (Optional) description – Free-text description of the ad group.
    • (Optional) context_hints – Context hints as a JSON array string, e.g. "['running shoes', 'trail']".
    • (Optional) custom_audience_bid_multipliers – Bid multipliers as a JSON array string.
    • (Optional) product_set – Product set as a JSON object string for product feed campaigns.
  • Example prompts
    • Create an ad group called "US Prospecting" under campaign campaign_abc123 bidding on clicks with a $0.50 max bid.
    • Add a paused ad group to my campaign with impression billing.
    • Set up an ad group with context hints for "trail running".
openai_ads_get_ad_group – Get a single OpenAI (ChatGPT) ad group by its ID.
  • When to use
    • Inspect an ad group's bidding config, max bid, billing event, and status in full detail.
    • Confirm ad group settings and targeting hints before updating or activating it.
    • Check parent campaign association and delivery settings.
  • Parameters
    • ad_group_id – The ID of the ad group to retrieve. Example: "adgroup_abc123".
  • Example prompts
    • Show me the settings for ad group adgroup_abc123.
    • What is the current max bid on this ad group?
    • Get the full configuration of our prospecting ad group.
openai_ads_list_ad_groups – List ad groups in the connected OpenAI (ChatGPT) ad account, optionally filtered to one campaign.
  • When to use
    • View ad groups under a specific campaign (pass campaign_id).
    • Discover ad group IDs before creating ads or modifying bids.
    • Audit ad group structure, bidding strategies, and delivery status across the account.
  • Parameters
    • (Optional) campaign_id – Only return ad groups belonging to this campaign. Example: "campaign_abc123".
    • (Optional) limit – Maximum number of ad groups to return (default: "25").
    • (Optional) order – Sort order by creation time: "asc" or "desc".
    • (Optional) after – Pagination cursor to return ad groups after this ID.
    • (Optional) before – Pagination cursor to return ad groups before this ID.
  • Example prompts
    • List all ad groups in campaign campaign_abc123.
    • Show me all ad groups in our account.
    • What ad groups exist under our Spring Launch campaign?
openai_ads_set_ad_group_status – Activate or pause an ad group in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Start an ad group serving (activate) so it can begin spending.
    • Stop an ad group from serving (pause) without archiving it.
    • Quickly toggle ad group spend on or off without altering bids or targeting.
  • Parameters
    • ad_group_id – The ID of the ad group to transition. Example: "ad_group_abc123".
    • action – "activate" (starts serving/spending) or "pause" (stops serving; reversible).
  • Example prompts
    • Activate ad group ad_group_abc123 so it starts serving.
    • Pause spend on ad group ad_group_123.
    • Temporarily stop this ad group.
openai_ads_update_ad_group – Update an existing ad group in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Raise or lower an ad group's max bid to optimize performance or adjust spend.
    • Rename an ad group or change its status ("active", "paused", "archived").
    • Update context hints, custom audience bid multipliers, or product set.
  • Parameters
    • ad_group_id – The ID of the ad group to update. Example: "ad_group_abc123".
    • (Optional) name – New ad group name (3–1000 characters).
    • (Optional) status – New status: "active", "paused", or "archived".
    • (Optional) billing_event_type – New billing event type: "impression" or "click" (required together with max_bid_micros).
    • (Optional) max_bid_micros – New max bid in micros (required together with billing_event_type).
    • (Optional) description – New description.
    • (Optional) context_hints – Replacement context hints as a JSON array string.
    • (Optional) custom_audience_bid_multipliers – Replacement bid multipliers as a JSON array string.
    • (Optional) product_set – Replacement product set as a JSON object string.
  • Example prompts
    • Raise the max bid on ad group ad_group_abc123 to $0.75.
    • Rename this ad group to "US High-Intent Prospecting".
    • Update context hints for ad group ad_123 to include "trail running shoes".

Ads and creatives

openai_ads_archive_ad – Permanently archive an ad in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Permanently retire an ad you no longer need (cannot be undone or reactivated).
    • Remove a finished or rejected ad from the active set.
    • Clean up ads that will never run again rather than just pausing them.
  • Parameters
    • ad_id – The ID of the ad to archive. Example: "ad_abc123".
  • Example prompts
    • Archive ad ad_abc123 permanently.
    • Remove this rejected ad from my account.
    • Clean up old inactive ads by archiving them.
openai_ads_create_ad – Create a new ad under an ad group in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Add a chat card or product ad template creative to an existing ad group.
    • Attach a click-through URL and an uploaded image to the creative.
    • Turn approved copy and imagery into a live-eligible ad (created paused by default).
  • Parameters
    • ad_group_id – The parent ad group ID. Example: "ad_group_abc123".
    • creative_type – Creative type: "chat_card" or "product_ad_template".
    • name – Ad name (3–1000 characters). Example: "Spring Hero Ad".
    • title – Creative title (3–50 characters). Example: "Meet the new runner".
    • body – Creative body text (max 100 characters).
    • (Optional) file_id – Image asset ID. Required for "chat_card". Upload first with openai_ads_upload_image.
    • (Optional) target_url – Click-through URL (max 2048 characters). Required for "chat_card".
    • (Optional) price – Price text (max 100 characters). Required for "product_ad_template".
    • (Optional) status – Initial status: "active" or "paused" (default: "paused").
  • Example prompts
    • Create a chat card ad named "Spring Hero" in ad group ad_group_abc123.
    • Build an ad with title "Meet the new runner" and link to https://example.com/shoes.
    • Set up a paused ad creative with my uploaded image file_abc123.
openai_ads_get_ad – Get a single OpenAI (ChatGPT) ad by its ID.
  • When to use
    • Retrieve full details for a specific ad, including creative copy, image, price, and status.
    • Inspect review/approval state and serving status of an ad.
    • Read an existing creative's file_id and target_url before updating or duplicating.
  • Parameters
    • ad_id – The ID of the ad to retrieve. Example: "ad_abc123".
  • Example prompts
    • Get the details for ad ad_abc123.
    • What does ad ad_123 look like right now?
    • Check the approval status of my ad.
openai_ads_list_ads – List ads in the connected OpenAI (ChatGPT) ad account, optionally filtered to one ad group.
  • When to use
    • Audit which ads exist across the account or within a specific ad group.
    • Check review/approval status and serving eligibility for ads.
    • Find ad IDs to retrieve details, adjust copy, or toggle serving status.
  • Parameters
    • (Optional) ad_group_id – Only return ads belonging to this ad group. Example: "adgroup_abc123".
    • (Optional) limit – Maximum number of ads to return (default: "25").
    • (Optional) order – Sort order by creation time: "asc" or "desc".
    • (Optional) after – Pagination cursor to return ads after this ID.
    • (Optional) before – Pagination cursor to return ads before this ID.
  • Example prompts
    • Which ads are live in ad group adgroup_abc123?
    • List all ads across our OpenAI ad account.
    • Check which ads are pending review in this ad group.
openai_ads_set_ad_status – Activate or pause an ad in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Activate a paused ad so it becomes eligible to serve and spend (subject to review).
    • Pause an active ad to stop it immediately without deleting or archiving it.
    • Toggle an ad's delivery state without touching creative copy or imagery.
  • Parameters
    • ad_id – The ID of the ad to transition. Example: "ad_abc123".
    • action – "activate" (starts serving/spending) or "pause" (stops serving; reversible).
  • Example prompts
    • Activate ad ad_abc123 so it starts spending.
    • Pause ad ad_abc123 to stop serving it.
    • Turn off this ad temporarily.
openai_ads_update_ad – Update an existing ad in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Rename an ad or change its status ("active", "paused", "archived").
    • Replace the ad's creative copy, price, image, or click-through URL.
    • Adjust an ad in place after review feedback (creative is replaced as a whole).
  • Parameters
    • ad_id – The ID of the ad to update. Example: "ad_abc123".
    • (Optional) name – New ad name.
    • (Optional) status – New status: "active", "paused", or "archived".
    • (Optional) creative_type – Creative type: "chat_card" or "product_ad_template" (required if changing creative).
    • (Optional) title – Creative title (required if changing creative).
    • (Optional) body – Creative body text (required if changing creative).
    • (Optional) file_id – Image asset ID (required for "chat_card" if changing creative; resend existing ID if unchanged).
    • (Optional) target_url – Click-through URL, max 2048 characters (required for "chat_card" if changing creative).
    • (Optional) price – Price text, max 100 characters (for "product_ad_template").
  • Example prompts
    • Rename ad ad_abc123 to "Spring Hero Ad (v2)".
    • Update the headline on ad ad_123 to "New runner in stock".
    • Change the click-through URL for my ad to https://example.com/shoes-v2.
openai_ads_upload_image – Upload an image (by URL) to the connected OpenAI (ChatGPT) ad account and get back a file ID.
  • When to use
    • Register a hosted image with the OpenAI ad account and obtain its file_id.
    • Prepare an image asset before creating a chat card ad creative with openai_ads_create_ad.
    • Upload account imagery or a favicon from a public URL.
  • Parameters
    • image_url – Publicly reachable HTTP/HTTPS URL of the image to upload. Example: "https://example.com/ad.png".
    • (Optional) purpose – Only "account_favicon" is supported; omit for ad creatives.
  • Example prompts
    • Upload the image at https://example.com/creative.png to my ad account.
    • Register this public image URL so I can use it in a chat card ad.
    • Upload our company logo as the account favicon.

Targeting and audiences

openai_ads_get_custom_audience – Get a single custom audience by ID from the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Retrieve the full details of a specific custom audience.
    • Verify an audience exists and check its status before referencing it in campaign targeting.
    • Inspect customer list metadata.
  • Parameters
    • custom_audience_id – The ID of the custom audience to fetch. Example: "custaud_abc123".
  • Example prompts
    • Get details for custom audience custaud_abc123.
    • Check the status of our VIP customers audience list.
    • Look up custom audience custaud_xyz.
openai_ads_list_custom_audiences – List custom audiences in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • View all custom customer lists available for targeting.
    • Look up custom audience IDs to reference in ad group bid multipliers or targeting.
    • Audit available audience segments before building campaigns.
  • Parameters
    • (Optional) limit – Maximum number of custom audiences to return (default: "25").
    • (Optional) order – Sort order by creation time: "asc" or "desc".
    • (Optional) after – Pagination cursor to return audiences after this ID.
    • (Optional) before – Pagination cursor to return audiences before this ID.
  • Example prompts
    • Which custom audiences can we target?
    • List all custom audiences in our OpenAI ad account.
    • Find the ID of our high-value customer audience.
openai_ads_search_geo – Search for locations (geo targeting IDs) in the OpenAI (ChatGPT) Ads platform.
  • When to use
    • Resolve a free-text location name (city, region, country) into the location ID needed for campaign targeting.
    • Disambiguate locations by canonical name, type, and country code.
    • Prepare location inclusions or exclusions for campaign targeting.
  • Parameters
    • q – Free-text location query. Examples: "New York", "California", "United Kingdom".
    • (Optional) limit – Max number of results to return (e.g. "10").
  • Example prompts
    • Find the geo targeting ID for "New York".
    • Search for location IDs in the United Kingdom.
    • Look up the location ID for California to target in our campaign.

Conversions and performance insights

openai_ads_create_conversion_event_setting – Create a conversion event setting in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Track a new conversion event (purchases, leads, checkouts, etc.) in the ad account.
    • Attach a conversion event to one or more existing conversion sources (pixels with IDs like "cds_...").
    • Set the attribution window for campaign performance tracking. Note: This tool cannot update or rename existing settings.
  • Parameters
    • name – A name for the event setting (e.g. "Orders").
    • event_type – Conversion event type: "order_created", "lead_created", "checkout_started", "page_viewed", "items_added", "contents_viewed", "appointment_scheduled", "app_installed", "app_opened", or "custom".
    • attribution_window_days – Attribution window in days (currently accepts "30").
    • source_ids – JSON array string of conversion source (pixel) IDs (e.g. "[\"cds_abc123\"]").
    • (Optional) custom_event_name – Custom event name when using event_type="custom".
  • Example prompts
    • Create a conversion event setting for "order_created" tied to pixel cds_123.
    • Set up lead tracking with a 30-day attribution window.
    • Track "checkout_started" events on my pixel.
openai_ads_get_conversion_insights – Get conversion insights (conversion counts) for a set of entities in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • Measure conversion counts driven by campaigns, ad groups, or ads.
    • Compare conversion volumes across specific date ranges.
    • Generate conversion reporting for specific entity IDs.
  • Parameters
    • aggregation_level – Aggregation level: "campaign", "ad_group", or "ad".
    • entity_ids – JSON array string of entity IDs matching the aggregation level, e.g. "[\"cmpn_abc123\"]".
    • time_ranges – JSON array string of time-range objects, e.g. "[{\"type\":\"date_range\",\"since\":\"2026-06-01\",\"until\":\"2026-06-30\"}]".
  • Example prompts
    • How many conversions did campaign cmpn_abc123 drive in June?
    • Get conversion counts for my top three ad groups last month.
    • Show conversion reporting for ad ad_123.
openai_ads_get_insights – Get performance insights (metrics) for the OpenAI (ChatGPT) ad account or a specific campaign, ad group, or ad.
  • When to use
    • Pull metrics (impressions, clicks, spend, CTR, CPC, CPM) at account, campaign, ad group, or ad level.
    • Break results down by time bucket (hourly, daily, monthly) and entity grain.
    • Report advertising spend and engagement performance over time.
  • Parameters
    • level – Scope of the insights: "ad_account", "campaign", "ad_group", or "ad".
    • (Optional) id – Entity ID for the chosen level. Required for "campaign", "ad_group", "ad"; omit for "ad_account".
    • (Optional) fields – JSON array string of metric names, e.g. "['impressions', 'clicks', 'spend', 'ctr', 'cpc']".
    • (Optional) time_granularity – Time bucket size: "hourly", "daily", "monthly", or "none".
    • (Optional) time_ranges – JSON array string of time-range objects with "since" and "until" dates in UTC (YYYY-MM-DD).
    • (Optional) aggregation_level – Entity grain within scope: "ad_account", "campaign", "ad_group", or "ad".
    • (Optional) limit – Max insight rows to return (e.g. "50").
  • Example prompts
    • Show total spend, clicks, and impressions for our ad account this month.
    • Get daily performance insights for campaign campaign_abc123.
    • What is the CTR and CPC for ad group adgroup_xyz over the last 30 days?
openai_ads_list_conversion_event_settings – List conversion event settings in the connected OpenAI (ChatGPT) ad account.
  • When to use
    • See which conversion events (e.g. purchases, leads) are currently tracked and attributed.
    • Look up conversion event setting IDs to attach to campaigns.
    • Audit pixel associations and attribution windows before launching new campaigns.
  • Parameters
    • (Optional) limit – Maximum number of settings to return (default: "25").
    • (Optional) order – Sort order by creation time: "asc" or "desc".
    • (Optional) after – Pagination cursor to return settings after this ID.
    • (Optional) before – Pagination cursor to return settings before this ID.
  • Example prompts
    • What conversions are we tracking?
    • List all conversion event settings in our ad account.
    • Find the conversion event setting ID for order purchases.