Skip to main content
GET
Get Perception

Authorizations

Authorization
string
header
required

An API key, sent as Authorization: Bearer hrld_....

Path Parameters

brand_id
string<uuid>
required

The brand's UUID from listBrands.

Query Parameters

market
string | null

Country ISO code, europe for pooled Europe, or global for no country. Omit for all.

audience

Audience UUID, or all_buyers for topics for all buyers. Omit for all.

engine
enum<string> | null

Answering AI engine.

Available options:
perplexity,
gemini,
openai,
google_aio,
ai_mode,
copilot,
claude
type
enum<string> | null

Question type.

Available options:
organic,
brand_specific,
competitor_comparison
intent
enum<string> | null

Question intent.

Available options:
educational,
problem,
comparison,
transactional
topic
string<uuid> | null

Tracked topic UUID.

prompt
string<uuid> | null

Question id from list_prompts.

as_of
string<uuid> | null

Completed scan id cutoff.

period
enum<string>
default:1w

Weekly-report period.

Available options:
1w,
4w,
12w,
all
list_limit
integer | null

Maximum rows in each supporting list.

Required range: 1 <= x <= 100
prompts_offset
integer
default:0

Related prompts to skip.

Required range: x >= 0
sources_offset
integer
default:0

Sources to skip.

Required range: x >= 0
pages_offset
integer
default:0

Pages or opinion holders to skip.

Required range: x >= 0

Response

Successful Response

best_quotes
V1PerceptionBestQuote · object[]
required
claims
V1PerceptionClaimRow · object[]
required
domain
string
required
facts_summary
FactSummary · object
required

Mostly-right and measured fact counts, plus fact keys with insufficient addressing answers.

filters
FigureFilters · object
required
headline
string | null
required

Written statement or templated sentence over served figures; null when Understood has no measured value.

meta
Meta · object
required

Normalized query and newest included scan.

negative_prompts
V1PerceptionNegativePrompt · object[]
required
negative_prompts_total
integer
required

All prompts with negative evidence before paging.

negative_sources
V1PerceptionNegativeSource · object[]
required
negative_sources_total
integer
required

All sources with negative evidence before paging.

period
V1Period · object
required
praised
V1Figure · object
required
understood
V1Figure · object
required

0.63 × the AI part + 0.37 × the web part; the AI part alone under ten documents or a filter.

written
V1PerceptionWrittenPieces · object
required

What the latest weekly report's interpretation wrote, over every answer and every engine: none of it follows the period or a filter.