Skip to main content
GET
Get Scores

Authorizations

Authorization
string
header
required

An organisation service token, sent as Authorization: Bearer hrld_svc_... Scopes: scans:start starts service scans; scans:read reads them; managed:read reads brands, profile, overview, scores, competitors, actions and Snapshots in actively managed organisations; managed:share makes their restricted Snapshots unlisted.

Path Parameters

brand_id
string<uuid>
required

The brand's UUID from listBrands.

Query Parameters

country
string | null

Check country or global. Omit for all.

limit
integer
default:10

Maximum rows (100).

Required range: 1 <= x <= 100
cursor
string | null

Prior next_cursor; keep filters and limit.

Maximum string length: 4096
as_of
string<uuid> | null

Completed scan id cutoff.

offset
integer
default:0

Rows to skip; prefer cursor paging.

Required range: x >= 0
side
enum<string>
default:all

Read AI answers (ai), Google shares without a score (search), or AI figures (all).

Available options:
all,
ai,
search
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
period
enum<string>
default:1w

Weekly-report period.

Available options:
1w,
4w,
12w,
all
preview
boolean
default:false

Include the selected engine’s bounded Work preview. Select a figure with pane_axis.

pane_axis
enum<string> | null

Read only this figure, including its bounded evidence.

Available options:
mentioned,
recommended,
understood,
praised
section
enum<string> | null

The selected section paged by limit and offset.

Available options:
weakest,
strongest,
sources,
brands,
work,
questions,
claims,
rankings,
ranking_pages,
markets
prompt
string<uuid> | null

Question id from list_prompts.

with_panes
boolean
default:false

Include figure details.

with_search_detail
boolean
default:false

Include Google rankings, pages, brands, markets and actions with side=search and either with_panes=true or pane_axis, scoped by topic, market and audience.

figure_only
boolean
default:false
deprecated

Return figures without supporting tables. Deprecated; sunset 2026-11-23.

group_by
enum<string> | null

Also state the figures per engine, intent, stage, prompt type, topic, prompt, competitor or country asked from, under the same period and filters.

Available options:
engine,
intent,
stage,
type,
topic,
prompt,
competitor,
country
include
enum<string> | null

Include the Engines table or details for the selected engine.

Available options:
engines,
engine
sort
enum<string>
default:score

Field to order results by.

Available options:
engine,
score,
trend,
mentioned,
recommended,
understood,
praised,
answers
direction
enum<string> | null

Order results ascending or descending.

Available options:
asc,
desc
with_menus
boolean
default:false

Include available filter choices.

with_cards
boolean
default:false

Include figure summaries.

with_trend
boolean
default:true

Include each figure's weekly trend. Without it, trend is empty.

you
enum<string> | null

Keep prompts or answers matching this brand-presence state.

Available options:
named,
not_named
you_engine

Resolve you on this engine, or all engines, before measuring the selected engine. Omit to resolve you under the engine filter.

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

Tracked topic UUID.

topic_id
string | null
deprecated

Deprecated topic selector; use topic for a tracked topic UUID.

Maximum string length: 100

Response

Successful Response

competitor_rank
V1CompetitorRank · object | null
required

Under group_by=competitor, your rank by Heralded Score among the tracked competitors in groups; null otherwise, or while your score or every competitor's is unmeasured.

engine
V1EnginePane · object | null
required
engine_weights
Engine Weights · object
required

Each engine's configured share of the AI side, from 0 to 1. Unchanged by filters.

engines
EnginesPage · object | null
required
groups
V1ScoreRow · object[] | null
required
headline
string | null
required

One sentence on how AI answers treat the brand under this read's filters, from templates with no model call. Null on side=search, before the first read and while no figure is measured.

heralded_score
V1Figure · object
required
mentioned
V1Figure · object
required
meta
Meta · object
required

Normalized query and newest included scan.

next_cursor
string | null
required

Pass as cursor with the same query to read the next page; null at the end.

pane_prompts
PerceptionPromptRow · object[]
required
pane_rivals
RivalAxes · object[]
required
panes
V1AxisPane · object[] | null
required
period
V1Period · object
required
praised
V1Figure · object
required
side_weights
Side Weights · object
required

Each side's share of All, from 0 to 1. AI is 1 and Search is 0 while Search is not scored. Unchanged by filters or availability.

sides_available
enum<string>[]
required

The sides the period's reports observed: ai, and search once a report checked keywords. A read of reports without search observations states ["ai"], and all is then the AI side.

Available options:
ai,
search
understood
V1Figure · object
required