API docs v1
GET /v1/brands/{brand_id}/openai-ads/performance

Read OpenAI Ads performance

scope read:ads cost 2 RU

Delivery and conversion metrics of the brand's OpenAI Ads for a window: impressions, clicks, spend, CTR, CPC, CPM, conversions, CPA, attributed sales and ROAS. level picks the scope (the whole ad_account, or one campaign, ad_group or ad named by entity_id) and group_by what each row stands for, at that level or below: the account grouped by campaign is one row per campaign. granularity daily or monthly splits each row by date. The attribution settings change every conversion number and are echoed back. OpenAI's report is kept up to an hour (15 minutes when split by date). Pages with limit and cursor.

The brand owner needs Pro or higher (403 brand_plan_required). A brand without an OpenAI Ads connection answers 400 integration_not_connected with details.connect_url. Free: no credits. Money is in micros of the ad account's currency (1,000,000 is one unit). start_date and end_date are YYYY-MM-DD; they default to the last 28 days, the window is at most 365 days, and OpenAI reports up to yesterday (UTC). Ads are paid, labeled placements in ChatGPT, separate from the organic answers the visibility reports measure.

Path parameters

Query parameters

  • start_date string optional

    First day of the window (YYYY-MM-DD).

  • end_date string optional

    Last day of the window (YYYY-MM-DD).

  • level string (enum) optional

    The scope read.

    one of ad_account, campaign, ad_group, ad · default: ad_account

  • entity_id string optional

    The campaign, ad group or ad, with that level.

  • group_by string optional

    What each row stands for, at level or below. Defaults to level.

  • granularity string (enum) optional

    none totals the window.

    one of none, daily, monthly · default: none

  • attribution_window_days integer (enum) optional

    Days after a click a conversion still counts: 7, 14 or 30.

    one of 7, 14, 30 · default: 30

  • view_through_attribution_window_days integer (enum) optional

    Days after a view a conversion still counts: 0 leaves views out.

    one of 0, 1 · default: 1

  • attribution_time_basis string (enum) optional

    ad_event_time files a conversion on the click or view's day, conversion_time on its own.

    one of ad_event_time, conversion_time · default: ad_event_time

  • limit integer optional

    Rows per page.

    default: 200

  • cursor string optional

    next_cursor of the previous page, unchanged.

  • dry_run boolean optional

    Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

    default: false

Responses

Read OpenAI Ads performance application/json
Type: AdsPerformance
  • attribution AdsAttribution required

    The attribution settings every conversion number in the response was counted with.

    Show fields
    Type: AdsAttribution
  • data array of AdsPerformanceRow required
  • end_date string required

    Last day read (YYYY-MM-DD); never later than yesterday in UTC.

  • granularity enum required

    none totals the window; daily and monthly split it.

  • group_by enum required

    What each row stands for.

  • has_more boolean required

    True when another page follows; pass next_cursor as cursor to read it.

  • level enum required

    The scope read: the whole account or one entity.

  • start_date string required

    First day read (YYYY-MM-DD).

  • currency string (nullable) nullable

    ISO 4217 code of the ad account, which money is in.

  • entity_id string (nullable) nullable

    The campaign, ad group or ad read; null for the account.

  • next_cursor string (nullable) nullable

    Opaque cursor for the next page; null on the last.

  • object string

    default: `openai_ads_performance`

Example response 
{
  "attribution": {
    "attribution_time_basis": "ad_event_time",
    "attribution_window_days": 30,
    "view_through_attribution_window_days": 1
  },
  "currency": "USD",
  "data": [
    {
      "attributed_sales_currency": "USD",
      "attributed_sales_micros": 5912000000,
      "clicks": 912,
      "conversions": 61,
      "cpa_micros": 21057377,
      "cpc_micros": 1408442,
      "cpm_micros": 26643850,
      "ctr": 0.018917,
      "entity_id": "cmp_8f2a1c",
      "entity_type": "campaign",
      "impressions": 48210,
      "name": "Running shoes, US",
      "object": "openai_ads_performance_row",
      "roas": 4.6,
      "spend_micros": 1284500000
    }
  ],
  "end_date": "2026-10-15",
  "granularity": "none",
  "group_by": "campaign",
  "has_more": false,
  "level": "ad_account",
  "object": "openai_ads_performance",
  "start_date": "2026-09-18"
}
Request validation failed application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Missing or invalid credentials application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
You do not have permission to access this resource application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource not found application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource conflict application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Per-minute rate limit exceeded application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
An unexpected error occurred application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Service temporarily unavailable, please retry application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}