How to collect ChatGPT Ads reports

Decide what the report should cover

Start with results by campaign and day for one ad account you have permission to use. Choose the dates and metrics, then keep the account’s time zone, currency and the time you collected the data with the report. A live request needs separate Advertiser API access. Reporting definitions and data updates

Reports show totals for the campaigns or ads you ask about. Individual conversations, the ads considered for them and their ranking scores stay inside the platform. Keep the Ads API key, a secret your software uses to sign in, on your server. Authentication and account scope

Define the result before choosing the interface. Return the requested scope, the scope actually covered, and a status with the reason collection stopped. A subtotal should identify the rows it covers so the caller can tell whether it answers the original question.

Ask Insights for daily campaign results

Insights is the part of the Ads API that returns performance reports. This request asks for one row per campaign per day, with the campaign ID, date, impressions, clicks and spend. Insights request reference

GET https://api.ads.openai.com/v1/ad_account/insights

aggregation_level=campaign
time_granularity=daily
fields[]=metadata.readable_time
fields[]=campaign.id
fields[]=campaign.impressions
fields[]=campaign.clicks
fields[]=campaign.spend
time_ranges[]={"type":"unix_range","start":1793491200,"end":1793577600}

# Query values must be URL-encoded.
# Authorisation is supplied by your server, never this page.

This request covers 1 November 2026 in UTC, the time standard used for the example. The end time is midnight at the start of 2 November, so the request excludes that day. Check the account’s reporting time zone if you want a local calendar day. The download labels OpenAI’s request fields and our own report fields separately.

Check that you have every batch

Pagination means asking for the next page of the same result. Splitting an oversized conversion report means making several smaller requests and combining their results. Use the rules for the report you asked for. Reporting limits

Show what your report is missing

{
  "reference_kind": "illustrative-reporting-envelope",
  "account_ref": "sample-account",
  "status": "partial",
  "coverage": {"completed_partitions": 2, "expected_partitions": 3},
  "missing_partitions": ["campaign-group-c"],
  "stop_reason": "retry_budget_exhausted"
}

In this example, two of three batches are ready and the remaining batch is named. Give temporary failures a bounded retry budget. If access is denied or the results cannot be validated, stop and return the batches you already accepted with the reason the report is incomplete.

To resume across runs in production, save the original request, accepted batches, and the next cursor. Use the campaign and date to avoid counting a row twice within this report. When figures arrive late, reconcile the newer snapshot for the same scope instead of adding both snapshots together.

Can you use this report?

Interpret credited conversions

Before comparing reports, check that the account, dates, time zone, currency, and attribution settings match. Check coverage and freshness too. An unavailable conversion count represents missing information. A newer snapshot may have a different count for the same dates.

An attributed conversion is an action the platform credits to an ad under its reporting rules. To estimate how many additional sales the campaign caused, define the outcome and compare it with a credible estimate of what would have happened without the campaign. A suitable holdout can provide that comparison.

Give an agent a bounded reporting tool

Give the tool one job: read a campaign report within an explicit scope. For a live design, the service should enforce account access and request limits. Return the scope, status, coverage, and freshness alongside the values so an agent can explain an incomplete result before recommending a decision.

The local MCP tool reads the bundled fictional reports. Its inputs select a scenario and a page limit. Try the partial scenario and check whether the agent can explain which totals are available and why collection stopped. The collector and adapter run instructions are below.

Reference downloads