OpenAI Ads Reporting

Retrieve performance insights aggregated across the entire ad account. Returns a list response (data[] with first_id/last_id/has_more for paging). Each row carries id, start_time, end_time, plus the projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name, and ad_name. Combine aggregation_level, sort, and limit to rank entities (e.g. the top ad by clicks). Monetary metrics (spend, cpc, cpm) are in the account's currency as decimal values, not micros.

Fetch a single ad by its ID, including its creative and review status.

Fetch the ad account associated with the configured API key. Use this as a connectivity check to confirm the key is valid, and to read account-level details such as name, currency, status, and timezone. Each API key is scoped to a single ad account.

Fetch a single ad group by its ID, including its status, bidding configuration, and context hints. Monetary values are expressed in micros: 1,000,000 micros = 1 unit of the account's currency (for example, $1.00 = 1,000,000 micros). Divide any *_micros value by 1,000,000 to show a human-readable amount, and multiply by 1,000,000 to convert a currency amount into micros.

Retrieve performance insights for a single ad group. Returns a list response (data[] with first_id/last_id/has_more for paging). Each row carries id, start_time, end_time, plus the projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name, and ad_name. Combine aggregation_level, sort, and limit to rank entities (e.g. the top ad by clicks). Monetary metrics (spend, cpc, cpm) are in the account's currency as decimal values, not micros.

Retrieve performance insights for a single ad. Returns a list response (data[] with first_id/last_id/has_more for paging). Each row carries id, start_time, end_time, plus the projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name, and ad_name. Combine aggregation_level, sort, and limit to rank entities (e.g. the top ad by clicks). Monetary metrics (spend, cpc, cpm) are in the account's currency as decimal values, not micros.

Fetch a single campaign by its ID, including its objective, status, budget, and targeting. Monetary values are expressed in micros: 1,000,000 micros = 1 unit of the account's currency (for example, $1.00 = 1,000,000 micros). Divide any *_micros value by 1,000,000 to show a human-readable amount, and multiply by 1,000,000 to convert a currency amount into micros.

Retrieve performance insights for a single campaign. Returns a list response (data[] with first_id/last_id/has_more for paging). Each row carries id, start_time, end_time, plus the projected fields such as impressions, clicks, spend, ctr, cpc, cpm, readable_time, campaign_name, ad_group_name, and ad_name. Combine aggregation_level, sort, and limit to rank entities (e.g. the top ad by clicks). Monetary metrics (spend, cpc, cpm) are in the account's currency as decimal values, not micros.

List ad groups within a campaign (campaign_id is required). Ad groups belong to a campaign and hold the bidding configuration and context hints. Supports cursor pagination (order, after/before; the response includes first_id, last_id, and has_more). Monetary values are expressed in micros: 1,000,000 micros = 1 unit of the account's currency (for example, $1.00 = 1,000,000 micros). Divide any *_micros value by 1,000,000 to show a human-readable amount, and multiply by 1,000,000 to convert a currency amount into micros.

List ads within an ad group (ad_group_id is required). Each ad holds a creative (title, body, target URL, image) and a review_status (in_review, approved, or rejected). Supports cursor pagination (order, after/before; the response includes first_id, last_id, and has_more).

List campaigns in the ad account. Campaigns are the top-level objects that define the objective, budget, and country targeting. Supports cursor pagination; the response includes first_id, last_id, and has_more. Monetary values are expressed in micros: 1,000,000 micros = 1 unit of the account's currency (for example, $1.00 = 1,000,000 micros). Divide any *_micros value by 1,000,000 to show a human-readable amount, and multiply by 1,000,000 to convert a currency amount into micros.