GET /v1/brands/{brand_id}/openai-ads/conversions

Read OpenAI Ads attributed conversions

Conversions OpenAI attributed to the brand's ads, from the pixel and the Conversions API: click-through, view-through, their total and the attributed sales, per group_by (campaign by default, ad_group, ad, or the whole ad_account). Without entity_ids every entity at that level is read. include_events=true nests each event's counts and value under its row (event_names keeps only some events there; the goal counts do not change). granularity=daily splits by day and breakdown by country or device. Every row comes back with totals; a report over OpenAI's 2,000 rows answers 400 validation_error: ask for fewer days or entities.

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

brand_id string required

Brand UUID.

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).
group_by string (enum) optional

What each row stands for.

one of ad_account, campaign, ad_group, ad · default: campaign
entity_ids string optional

Only these campaigns, ad groups or ads (repeat it); every one at group_by when omitted.
granularity string (enum) optional

none totals the window.

one of none, daily · default: none
breakdown string optional

Split rows by country or device.
include_events boolean optional

Nest each event's attributed counts and value.

default: false
event_names string optional

With include_events, only these events (repeat it).
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
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 attributed conversions application/json

Type: AdsConversions

attribution AdsAttribution required

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

Type: AdsAttribution
- attribution_time_basis enum required
  
  ad_event_time files a conversion on the day of the click or view, conversion_time on its own day.
- attribution_window_days enum required
  
  Days after a click a conversion still counts.
- view_through_attribution_window_days enum required
  
  Days after an ad was only seen a conversion still counts; 0 leaves views out.
data array of AdsConversionRow required

Every row; the report is not paginated.
end_date string required

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

none totals the window; daily splits it.
group_by enum required

What each row stands for.
start_date string required

First day read (YYYY-MM-DD).
totals AdsConversionTotals required

Every row summed.
Show fields

Type: AdsConversionTotals
- click_through_conversions integer required
  
  Conversions after a click.
- conversions integer required
  
  Click-through plus view-through conversions.
- view_through_conversions integer required
  
  Conversions after a view only.
- attributed_sales_currency string (nullable) nullable
  
  ISO 4217 code of the sales.
- attributed_sales_micros integer (nullable) nullable
  
  Attributed purchase value in micros of attributed_sales_currency; null when none had a value.
breakdown enum (nullable) nullable

The extra split asked for, if any.
currency string (nullable) nullable

ISO 4217 code of the ad account.
object string

default: `openai_ads_conversions`

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,
      "click_through_conversions": 47,
      "conversions": 61,
      "entity_id": "cmp_8f2a1c",
      "entity_type": "campaign",
      "events": [
        {
          "click_through_conversions": 40,
          "count": 52,
          "event_kind": "standard",
          "event_name": "order_created",
          "value_currency": "USD",
          "value_micros": 5912000000,
          "view_through_conversions": 12
        }
      ],
      "name": "Running shoes, US",
      "object": "openai_ads_conversion_row",
      "view_through_conversions": 14
    }
  ],
  "end_date": "2026-10-15",
  "granularity": "none",
  "group_by": "campaign",
  "object": "openai_ads_conversions",
  "start_date": "2026-09-18",
  "totals": {
    "attributed_sales_currency": "USD",
    "attributed_sales_micros": 5912000000,
    "click_through_conversions": 47,
    "conversions": 61,
    "view_through_conversions": 14
  }
}

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"
}

Request example

curl --request GET \
  --url 'https://api.rankprompt.com/v1/brands/your_brand_id_here/openai-ads/conversions?start_date=your_start_date_here&end_date=your_end_date_here&group_by=campaign&entity_ids=your_entity_ids_here&granularity=none&breakdown=your_breakdown_here&include_events=false&event_names=your_event_names_here&attribution_window_days=30&view_through_attribution_window_days=1&attribution_time_basis=ad_event_time&dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/brands/your_brand_id_here/openai-ads/conversions?start_date=your_start_date_here&end_date=your_end_date_here&group_by=campaign&entity_ids=your_entity_ids_here&granularity=none&breakdown=your_breakdown_here&include_events=false&event_names=your_event_names_here&attribution_window_days=30&view_through_attribution_window_days=1&attribution_time_basis=ad_event_time&dry_run=false';
const options = {method: 'GET', headers: {Authorization: 'Bearer rp_live_<YOUR_API_KEY>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/brands/your_brand_id_here/openai-ads/conversions"

querystring = {"start_date":"your_start_date_here","end_date":"your_end_date_here","group_by":"campaign","entity_ids":"your_entity_ids_here","granularity":"none","breakdown":"your_breakdown_here","include_events":"false","event_names":"your_event_names_here","attribution_window_days":"30","view_through_attribution_window_days":"1","attribution_time_basis":"ad_event_time","dry_run":"false"}

headers = {"Authorization": "Bearer rp_live_<YOUR_API_KEY>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())