AI Knowledge Hub
Menu

Tools Mcp / Adtech

OpenAI Ads API Client

Preferred executable client for bounded mock or live read-only OpenAI Ads retrieval and non-persisting Conversions API validation.

Access

Read only · OpenAI Advertiser API and Ads Conversions API

Setup requiredLocal programRequirements & limits

Inputs

  • A selected operation and account scope
  • Packaged fixtures for mock mode, or separately configured credentials for live reads

Outputs

  • Bounded account, campaign, ad or insights data for the selected operation
  • Local or non-persisting conversion-validation results when requested

Before you begin

  • Python 3.9 or newer for mock mode. Review the tool contract before connecting an account.

Try this first

Inspect the packaged offline sample before running it. After file installation, use the stated runtime from the installed package directory.

Limits for this step
  • Mock mode is immediately runnable, but provider-backed readiness requires an available account-scoped API key.
  • The provider account endpoint attests the account binding, not the individual human owner of an API key.
  • Campaign, ad-group, ad, file, feed, and persisted conversion mutations are intentionally excluded.
  • Automatic pagination, retries, and rate-limit backoff are not included.
  • Advertiser operations are GET-only; bounded Conversions API requests force validate_only true and cannot persist events.
Inspect offline sampleHide offline sampleSynthetic example

Runtime · Python 3.9 or newer. Run from the installed package directory after file installation.

python3 scripts/openai_ads_client.py --mode mock account

Expected result · The packaged mock account response. This sample makes no provider call.

This is the release’s documented sample, separate from evidence of operation in your environment.

Summary sources · Catalogue metadata, tool.yaml, README.md, TOOL.md, examples/account.json · v0.2.0 · Release package

View capabilities and accessHide capabilities and accessv0.2.0

What it can do

  • Read bounded ad-account metadata, campaigns, ads, and account or entity insights.
  • Verify an account-scoped Ads API key against the provider ad-account endpoint.
  • Validate conversion batches locally or through non-persisting provider validation.

Access limits

Advertiser operations are GET-only; bounded Conversions API requests force validate_only true and cannot persist events.

Trust boundary · third-party-hosted

Credentials and setup

  • OPENAI_ADS_API_KEY for live Advertiser API reads
  • OPENAI_ADS_PIXEL_ID and OPENAI_ADS_CONVERSIONS_API_KEY for optional remote conversion validation

Install tool files

These commands install package files and generate runtime configuration where supported. Confirm discovery in your agent app, then check configuration, authentication and a first useful operation.

Install (Codex)

./bin/skills-hub install --module tools --entry adtech/[email protected] --runtime codex

Install (Claude)

./bin/skills-hub install --module tools --entry adtech/[email protected] --runtime claude

Install (Generic)

./bin/skills-hub install --module tools --entry adtech/[email protected] --runtime generic --target ./my-agent/tools-mcp

How You Can Use This

Setup required

Resource form: Local program

Configuration, credentials or runtime bindings are required. Check the prerequisites and limits for your intended environment.

First run: python3 scripts/openai_ads_client.py --mode mock account

Setup required

  • Python 3.9 or newer.
  • For live reads, create an account-scoped key in OpenAI Ads Manager and bind OPENAI_ADS_API_KEY outside agent context.
  • Configure separate pixel and Conversions API credentials only when provider-side validate-only checks are required.

Current limits

  • Mock mode is immediately runnable, but provider-backed readiness requires an available account-scoped API key.
  • The provider account endpoint attests the account binding, not the individual human owner of an API key.
  • Campaign, ad-group, ad, file, feed, and persisted conversion mutations are intentionally excluded.
  • Automatic pagination, retries, and rate-limit backoff are not included.
What installation and verification mean
File installation
Places package files and generated configuration in the selected directories.
Native discovery
Your agent app finds and accepts the instructions, tools or plugin registrations.
Mock execution
Exercises sample fixtures. Connected data and provider effects need a separate check.
Connected operation
Requires current configuration, provider authentication, scoped permissions and a successful operation in your intended environment.

Declared compatibility

Maintainer-reviewed information for version 0.2.0 · Reviewed 2026-10-31. This is not a live provider check.

  • Packaged API targets: Advertiser API /v1 and Ads Conversions API /v1/events
  • Runtime: Python 3.9 or newer
  • Uses the Python standard library; no OpenAI SDK is packaged.

Limits

  • Mock mode runs locally. Live Advertiser reads require an account-scoped Ads API key; optional remote conversion validation needs separate pixel and Conversions API credentials.
  • Advertiser operations are GET-only. Conversion requests force validate_only; persisted conversions and campaign mutations are excluded.
  • Automatic pagination, retries and rate-limit backoff are not included.

Reviewed OpenAI Ads release implementation

Classification: declared

Technical details and release files

Review and lifecycle

Review maturity: Experimental

Security review declaration: Not declared

Lifecycle: Active

These release declarations are separate from evidence that a workflow operates in your environment.

Runtime & Dependencies

ID: adtech/openai-ads-api-client

Tags: openai-ads, advertiser-api, campaign-insights, conversions-api, read-only

Runtimes: codex, claude, generic

Dependencies & Setup

MCP servers: Not documented

APIs: OpenAI Advertiser API, OpenAI Ads Conversions API

Local tools: python3