Get metadata for the ad account associated with the API key. Use to verify auth, check timezone/currency/review status. No chaining needed — call first to confirm key works.

List ad accounts accessible to the authenticated key/OAuth token. Returns accounts with ids for use as ad_account_id in other tools.

Update ad account brand metadata (name, url, etc.). Requires account be enabled for programmatic brand updates or it will 403. Chain after get_ad_account to see current values.

Replace account-level negative keywords used for ad eligibility. Provide full desired list — this is a replace, not append. Use to block unwanted contexts.

Activate the ad account (resume serving). All parent campaigns/ad groups/ads must also be active to serve.

Pause the ad account (stop all serving). Reversible via activate_ad_account.

View spend limit windows (inclusive start, exclusive end, ordered by start ascending). Use to audit or plan budget caps.

Create a spend limit window with inclusive start and exclusive end. Use to cap spend over a date range.

Edit a spend limit window (inclusive start, exclusive end). Provide window_id from get/create.

Delete an active or scheduled spend limit window before it ends.

Return the authenticated user's stable opaque ID (OAuth only). Useful for partner flows to verify token identity.

Create an API key scoped to the selected ad account (requires AdsOAuth with write or an existing API key with permission). Returns the new key — store it securely, it won't be shown again.

List campaigns for the ad account. Paginated. Use returned campaign_id with get_campaign, update_campaign, create_ad_group, and insights tools. Filter by name if needed.

Get a single campaign by ID. Use include=[serving_issues] to audit delivery problems. Returned id chains to ad group creation.

Create a campaign. Returns campaign_id for chaining to create_ad_group. Common next: create_ad_group with campaign_id. Supports idempotency key to avoid duplicates on retry.

Update a campaign by ID. Only provided fields are updated. Omitted optional fields reset to defaults except where noted. Send null to clear description/start_time/end_time.

Activate a paused campaign. All ancestors must be active for ads to serve.

Pause an active campaign. Reversible via activate_campaign.

Archive a campaign (terminal — cannot be reactivated via activate).

List ad groups for the ad account, optionally filtered by campaign_id. Use returned ad_group_id to create ads or fetch insights.

Get a single ad group by ID.

Create an ad group for a campaign. Returns ad_group_id for chaining to create_ad. Requires campaign_id + bidding_config.

Update an ad group by ID.

Activate a paused ad group.

Pause an active ad group.

Archive an ad group (terminal).

List ads for the ad account, optionally filtered by campaign_id or ad_group_id. Use ad_id for get_ad / insights / preview.

Get a single ad by ID. Check review_status to monitor approval (typically minutes).

Create an ad for an ad group. Requires creative (type/title/body etc.). For chat_card, provide file_id from upload_image. For product_ad_template, use {{product.*}} tokens and omit file_id. Returns ad_id.

Update an ad by ID. Only provided fields are updated.

Create a temporary iframe preview for an existing ad. Returns preview URL/html for QA before activating.

Activate a paused ad. Campaign and ad group must also be active + review approved to serve.

Pause an active ad.

Archive an ad (terminal).

Get ad account insights aggregated by time granularity. Attribution for current local day is preliminary. Use time_ranges + fields + segments for breakdowns. Paginated (limit/after/before).

Get campaign insights. Chain from list_campaigns -> campaign_id. Same params as ad account insights but scoped to one campaign.

Get ad group insights. Chain from list_ad_groups -> ad_group_id.

Get ad insights for a single ad. Check creative-level performance.

Get attributed conversion totals or daily values. POST /conversions/insights. Requires aggregation_level + time_ranges. Use breakdown (device/country) for segments. group_by_entity splits per campaign/ad_group/ad.

Upload a creative image for ads. Provide EITHER image_url (https) OR image_base64 (data). image_url is SSRF-guarded (https only, no private hosts). Returns file_id to use in create_ad creative.file_id. For chat_card ads, upload first then create_ad.

Upload a file for custom audience creation (CSV/TXT up to 500MB). Returns file_id (oaisdmntci_...) to use in create_custom_audience or add_audience_members. Provide file_base64 (base64 of CSV/TXT). Purpose is always custom_audience.

List custom audiences. Filter by intended_use, ids, or policy_revision for eligibility. Returns audiences with membership_revision for mutations. Paginated.

Create a custom audience from an uploaded file (provide file_id) or as empty/small audience if enabled. Processing is async — poll via get_custom_audience until published. Returns custom_audience_id.

Get a custom audience by ID. Check processing state and membership_revision before mutations.

Archive a custom audience. Archived audiences cannot be used for targeting.

Add identifiers to an existing custom audience (file or inline). Requires Idempotency-Key and expected_revision. Poll operation via get_audience_operation. Supports up to ~10k inline identifiers; use file for larger.

Remove identifiers from a custom audience (file or inline). Requires Idempotency-Key and expected_revision. Poll via get_audience_operation.

Replace all members of a custom audience using an uploaded file and current revision. Requires Idempotency-Key. Poll via get_audience_operation.

Create a new audience containing all matched members from 2–64 source audiences. Independent copy. Requires Idempotency-Key.

Retrieve lifecycle state of a custom audience mutation (add/remove/replace/merge). Poll with backoff. States: processing → succeeded/failed. Save operation_id from mutation response.

List eligible Business Agent tools installed for the authenticated API project. Use to discover connectors/tools available for business agent creation.

List Business Agents for the ad account. Each has id, name, status draft/published, etc.

Create a draft Business Agent. Requires name 1–50 + instructions 1–4000. Optionally attach product feeds, connectors, lead form. Publish separately via publish_business_agent.

Get a Business Agent by ID.

Replace a Business Agent's name and config and save as draft. Omitted optional fields reset to defaults (except lead_form preserved if omitted; send null to unlink). Requires full desired state.

Preview a response from a Business Agent. Useful for QA before publishing. Provide a test message.

Publish a Business Agent draft to make it live. Ensure preview looks good first.

List Lead Forms for the ad account.

Create a draft Lead Form. Requires name 1–256 + fields 3–5 (each: field_id, field_type text|choice, label, required, options for choice). Publish after creation.

Get a Lead Form by ID. Optionally specify rev_id for a specific revision.

Save a new draft revision for a Lead Form. Requires expected_draft_revision_id for conflict detection.

Publish the current Lead Form draft. After publishing, the form can be attached to a Business Agent.

Archive a Lead Form that is not attached to a published Business Agent.

Queue a synthetic signed lead-sync webhook test delivery for a Lead Form. Requires Idempotency-Key. Useful to validate webhook handling before going live.

Provision lead delivery to a managed webhook endpoint for an ad account. Requires Idempotency-Key and destination URL. Leads will be POSTed with Standard Webhooks HMAC signature.

List lead-sync subscriptions for an ad account. Requires ad_account_id query param.

Get a lead-sync subscription by ID.

Delete a lead-sync subscription to stop webhook delivery.

Create a conversion pixel (client data source) for the ad account. Returns pixel id (pid) used for event attribution and listing sampled events. Chain to create_conversion_api_key and create_conversion_event_setting.

List conversion pixels and connected pixel IDs for the ad account. Use pid from here with list_conversion_events.

Create a Conversions API key for the ad account (used to send server-side events via bzr.openai.com outside this MCP). Returns api_key — store securely, single display.

Create a conversion event setting linking an event type to source pixel(s). Used for conversions bidding (bidding_type=conversions) and conversion_event_setting_ids on campaigns. Requires name + event_type + source_ids.

List conversion event settings for the ad account. Use IDs with campaign conversion_event_setting_ids and conversions bidding.

List recent sampled conversion events for a pixel (requires pid). Up to 50 per call. Use to verify ingestion from bzr.openai.com.

Create a product feed for the ad account (merchant catalog). For SFTP-fetched catalogs, configure SFTP after. Use list_product_feeds to see existing.

List product feeds for the ad account. Use feed_id with query/patch/sftp tools.

Archive a product feed. Archived feeds cannot be used for new campaigns.

List recent product feed uploads (ingestion history). Useful to debug catalog fetch issues.

List products in a feed matching ad group product filters. Use to validate targeting before creating ad_group with product_set.

Update product availability and prices for a feed (delta without full SFTP re-upload). Provide product patches with item identifiers.

Get SFTP access details for a product feed (host, username, path). Use to configure catalog uploads.

Create or replace SFTP access credentials for a product feed. Returns credentials to configure your SFTP client.

Activate SFTP access for a product feed (resume ingestion).

Pause SFTP access for a product feed (stop ingestion).

Search DMA and standard region codes for advertiser geo targeting. Use returned location IDs with campaign targeting.locations.include. Chain: search_geo_lookup {q:'California'} -> create_campaign {targeting:{locations:{include:[...ids]}}}

Create an Ads partner-data upload (for partner integrations). Returns upload id for polling via get_partner_data_upload.

Get an Ads partner-data upload by ID (e.g., pdu_...). Poll to check processing status.

Composite workflow: create a full campaign -> ad group -> ad chain in one call. Useful for quick end-to-end creation. Returns all three IDs. If any step fails, earlier objects remain — use update/archive tools to clean up. Prefer atomic tools (create_campaign, create_ad_group, create_ad) for fine-grained control.

Helper to poll a custom audience mutation until terminal. Calls get_audience_operation once and returns current state. Call repeatedly with backoff (processing -> succeeded/failed). Does NOT loop internally — agent controls retry timing to respect rate limits.