Insights - Thrad API Documentation

The insights surface is four read-only endpoints, one per scope in the hierarchy. Each returns a bare list of metric rows for the entity you ask about (and, via aggregation_level, the levels below it). Numbers combine Thrad and ChatGPT (OpenAI Ads) supply by default; you can isolate or split a single supply.

GET /v1/ad_account/insights
GET /v1/campaigns/{campaign_id}/insights
GET /v1/ad_groups/{ad_group_id}/insights
GET /v1/ads/{ad_id}/insights

All four take the same query parameters and return the same list shape. The only difference is scope: the entity you target and the deepest aggregation_level you may request.

Insights money is dollar floats, not micros. spend, cpc, and cpm are already in dollars (e.g. 0.70), and ctr is a fraction (e.g. 0.10 = 10%). This is deliberately different from the resource endpoints (campaigns, ad groups, ads), where budgets and bids are integer micros ($1 = 1,000,000).

Authorizations

Authorization

string

required

Bearer token using your organization’s API key: Authorization: Bearer ak_.... There is one active key per organization — create or rotate it in the Thrad Platform dashboard under Settings → API keys. Store it as the THRAD_ADS_API_KEY environment variable.

Query parameters

These apply to every insights endpoint. Repeated parameters use the name[] convention (e.g. fields[]=impressions&fields[]=clicks).

time_granularity

string

default:"daily"

How rows are bucketed over time: hourly, daily (default), monthly, or none. With none a single row covers the whole requested range and has no readable_time. monthly rolls daily data up by calendar month. Any other value returns invalid_value.

aggregation_level

string

The row grain: ad_account, campaign, ad_group, or ad. Defaults to the endpoint’s own scope. It must be at or below the endpoint scope — e.g. GET /v1/campaigns/{id}/insights?aggregation_level=ad returns one row per ad in that campaign, but aggregation_level=ad_account on a campaign endpoint is rejected with aggregation_level_too_high. Use a deeper level to discover the entity ids beneath a scope; there are no separate list endpoints.

time_ranges[]

array

One or more JSON window objects. Each must be one of three types, and each window may span at most 366 days (range_too_wide). When omitted, a trailing 30-day window is used.

Show time_ranges[] object

unix_range

object

{"type":"unix_range","start":<unix>,"end":<unix>} — start and end are Unix seconds (UTC).

date_range

object

{"type":"date_range","since":"YYYY-MM-DD","until":"YYYY-MM-DD","timezone":"UTC"} — calendar dates. timezone is an optional IANA name (defaults to UTC); an unknown name returns invalid_time_range.

hour_range

object

{"type":"hour_range","since":"YYYY-MM-DDTHH","until":"YYYY-MM-DDTHH","timezone":"UTC"} — hour-precision bounds, pairs with time_granularity=hourly.

end must be after start (invalid_time_range). With time_granularity=hourly, each window must also be 25 hours or less (hourly_range_too_wide).

fields[]

array

Which metrics to project onto each row: impressions, clicks, spend, ctr, cpc, cpm. Defaults to impressions, clicks, spend. A dotted form like ad.impressions is accepted (the prefix is ignored). An unknown metric returns unknown_field.

filters[]

array

One or more JSON { "field", "operator", "value" } objects. Three kinds of field are accepted:

Show filters[] field kinds

metric filter

object

field is a metric (spend, clicks, ctr, …). Operator may be IN, GREATER_THAN, or LESS_THAN. GREATER_THAN/LESS_THAN require a numeric value. Metric filters are applied in memory to the computed rows.

entity-id filter

object

field is an entity id (campaign.id, ad_group.id, ad.id, or the _id form). Operator must be IN with a list value of public ids. These narrow the SQL scope and are org-resolved, so a cross-org or unknown id simply matches nothing. The id level cannot be finer than aggregation_level (else invalid_filter).

source filter

object

{"field":"source","operator":"IN","value":["thrad"]} — selects supply, equivalent to the source parameter. Operator must be IN. If you pass both this and source and they disagree, the request is rejected with invalid_filter.

An unknown field returns invalid_filter; a disallowed operator returns invalid_filter_operator.

sort[]

array

One or more JSON { "field", "direction" } objects, applied in order. field is a metric (ad.clicks accepted); direction is asc or desc. A non-metric field or a bad direction returns invalid_value. Row id is always the final deterministic tiebreak.

segments[]

array

Break each row into sub-rows along one dimension. At most one segment (too_many_segments otherwise).

source — split into thrad + openai sub-rows. Supported at every level; the sub-rows sum to the combined total.
country / device — break by country_code / device_type. Ad-group or ad scope only (unsupported_segment higher up), Thrad supply only (segment_source_unsupported if source=openai), and only none or daily granularity (segment_granularity_unsupported). This path aggregates a single window, so it rejects an entity-id filters[] (unsupported_segment) and more than one time_ranges[] (invalid_time_range).
product — not supported (unsupported_segment). Any other value returns invalid_segment.

source

string

default:"all"

Which supply to report: thrad, openai, or all (default — combined Thrad + ChatGPT). A convenience equivalent to the source filter above.

ChatGPT (OpenAI Ads) insights are daily-only. source=openai with time_granularity=hourly is a hard error (hourly_unsupported_for_external_source); a combined (all) hourly request silently reports Thrad supply only.

limit

integer

default:"20"

Maximum rows in the page, 1–2000 (default 20). Out of range returns invalid_value.

before

string

Cursor for the previous page — pass a prior response’s first_id. Mutually exclusive with after (invalid_cursor if both). An unknown cursor returns invalid_cursor.

after

string

Cursor for the next page — pass a prior response’s last_id. Mutually exclusive with before.

includes[] and override_segment_group_order[] exist in OpenAI’s Ads API but are not supported here. Passing either returns 400 unsupported_parameter — they are never silently ignored.

curl -G https://api.thrad.ai/v1/campaigns/$CAMPAIGN_ID/insights \
  -H "Authorization: Bearer $THRAD_ADS_API_KEY" \
  --data-urlencode 'time_granularity=daily' \
  --data-urlencode 'fields[]=impressions' \
  --data-urlencode 'fields[]=clicks' \
  --data-urlencode 'fields[]=spend' \
  --data-urlencode 'fields[]=ctr' \
  --data-urlencode 'time_ranges[]={"type":"date_range","since":"2026-04-01","until":"2026-04-03"}'

{
  "object": "list",
  "data": [
    {
      "id": "start=1775347200:end=1775433600:entity_id=8c1f...",
      "start_time": 1775347200,
      "end_time": 1775433600,
      "readable_time": "2026-04-02",
      "timezone": "UTC",
      "campaign_id": "8c1f2a3b-4d5e-6f70-8192-a3b4c5d6e7f8",
      "campaign_name": "Spring Sale",
      "impressions": 500,
      "clicks": 50,
      "spend": 0.70,
      "ctr": 0.1
    }
  ],
  "count": 1,
  "first_id": "start=1775347200:end=1775433600:entity_id=8c1f...",
  "last_id": "start=1775347200:end=1775433600:entity_id=8c1f...",
  "has_more": false
}

Response

Every endpoint returns the same bare list object — not the platform { success, data, error, meta } envelope.

object

string

Always "list".

data

array

The metric rows for this page. Each row is a flat object.

Show row properties

string

The row’s opaque id, used as a pagination cursor. Composed as start=<unix>:end=<unix>:entity_id=<uuid>, with :source=<thrad|openai> and/or :<segment>=<value> appended when those breakouts are present.

start_time

integer

Bucket start as Unix seconds (UTC).

end_time

integer

Bucket end as Unix seconds (UTC), exclusive.

readable_time

string

Human-readable bucket label — 2026-04-02 (daily), 2026-04 (monthly), or 2026-04-02T13 (hourly). Omitted when time_granularity=none.

timezone

string

Always "UTC".

<level>_id

string

The entity public id for this row, keyed by aggregation_level — e.g. campaign_id, ad_group_id, ad_id, or ad_account_id.

<level>_name

string

The entity’s display name, e.g. campaign_name.

source

string

thrad or openai. Present only when the rows are split by supply (segments[]=source).

country

string

The country_code for this sub-row. Present only with segments[]=country.

device

string

The device_type for this sub-row. Present only with segments[]=device.

impressions

integer

Impression count. Present when requested in fields[] (default).

clicks

integer

Click count. Present when requested in fields[] (default).

spend

float

Spend in dollars (e.g. 0.70), not micros. Present when requested in fields[] (default).

ctr

float

Click-through rate as a fraction (clicks ÷ impressions, e.g. 0.1 = 10%). null when impressions are zero. Present only when requested in fields[].

cpc

float

Cost per click in dollars (spend ÷ clicks). null when clicks are zero. Present only when requested in fields[].

cpm

float

Cost per thousand impressions in dollars (spend ÷ impressions × 1000). null when impressions are zero. Present only when requested in fields[].

count

integer

Number of rows in data on this page.

first_id

string

Id of the first row in the page. Pass it as before to fetch the previous page. null for an empty page.

last_id

string

Id of the last row in the page. Pass it as after to fetch the next page. null for an empty page.

has_more

boolean

true if more rows exist beyond this page.

Choosing supply (Thrad vs ChatGPT)

By default insights combine Thrad and ChatGPT (OpenAI Ads) supply into one number. There are three ways to look at supply individually:

source=thrad|openai — report a single supply. source=all (the default) is combined.
filters[]={"field":"source","operator":"IN","value":["thrad"]} — the OpenAI-style equivalent. If you also pass source and the two disagree, you get invalid_filter.
segments[]=source — keep the combined window but split each row into a thrad sub-row and an openai sub-row. Each sub-row carries a source field and :source=… in its id, and the two sum to the combined total.

Errors

Errors use the bare OpenAI shape — { "error": { "message", "type", "param", "code" } } — not the platform envelope. type is one of invalid_request_error, authentication_error, rate_limit_error, or server_error.

Status	Type	Code	When
`400`	`invalid_request_error`	`invalid_value`	A parameter has a bad value (`time_granularity`, `aggregation_level`, `source`, `sort`, `limit`, …).
`400`	`invalid_request_error`	`aggregation_level_too_high`	`aggregation_level` is above the endpoint’s scope.
`400`	`invalid_request_error`	`invalid_time_range`	A `time_ranges[]` entry is malformed, has `end` ≤ `start`, an unknown timezone, or (audience segments) more than one range.
`400`	`invalid_request_error`	`range_too_wide`	A window exceeds the 366-day maximum.
`400`	`invalid_request_error`	`hourly_range_too_wide`	An `hourly` window exceeds 25 hours.
`400`	`invalid_request_error`	`hourly_unsupported_for_external_source`	`source=openai` requested with `time_granularity=hourly`.
`400`	`invalid_request_error`	`unknown_field`	A `fields[]` value is not a known metric.
`400`	`invalid_request_error`	`invalid_filter`	A `filters[]` entry is malformed, references an unknown field, filters an id finer than `aggregation_level`, or its source disagrees with `source`.
`400`	`invalid_request_error`	`invalid_filter_operator`	A `filters[]` operator is not allowed for that field.
`400`	`invalid_request_error`	`too_many_segments`	More than one `segments[]` value.
`400`	`invalid_request_error`	`invalid_segment`	An unrecognized `segments[]` value.
`400`	`invalid_request_error`	`unsupported_segment`	`product` segment, or `country`/`device` outside ad-group/ad scope (or with an entity-id filter).
`400`	`invalid_request_error`	`segment_source_unsupported`	`country`/`device` segment with `source=openai` (Thrad supply only).
`400`	`invalid_request_error`	`segment_granularity_unsupported`	`country`/`device` segment with `hourly` or `monthly` granularity.
`400`	`invalid_request_error`	`invalid_cursor`	`before` and `after` both passed, or an unknown cursor.
`400`	`invalid_request_error`	`unsupported_parameter`	`includes[]` or `override_segment_group_order[]` was passed.
`401`	`authentication_error`	`auth_required`	No `Authorization` header was sent.
`401`	`authentication_error`	`invalid_api_key`	The `Authorization: Bearer ak_...` key is malformed, unknown, or revoked.
`404`	`invalid_request_error`	`not_found`	The path entity does not exist or belongs to another organization.
`429`	`rate_limit_error`	`rate_limit_exceeded`	Exceeded the per-key limit of 1000 requests/hour.
`504`	`server_error`	`clickhouse_timeout`	The analytics query timed out. Narrow the scope, window, or granularity and retry.

A single response is capped at a fixed maximum number of rows (the decoded set is sorted, filtered, and paginated in memory). If you need more, narrow the scope or window, or page with before/after.

​Authorizations

​Query parameters

​Response

​Choosing supply (Thrad vs ChatGPT)

​Errors

Authorizations

Query parameters

Response

Choosing supply (Thrad vs ChatGPT)

Errors