Skip to main content
GET
Get Overview

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

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.

side
enum<string>
default:all

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

Available options:
all,
ai,
search
as_of
string<uuid> | null

Completed scan id cutoff.

period
enum<string>
default:1w

Weekly-report period.

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

Add diagnosis: the prompts and sources rivals win over the last week, and the drafts ready to answer them.

lean
boolean
default:false

Omit rivals, sources, actions, attribution and readiness, and read none of them. They come back empty or null, and source_citation_evidence and source_unavailable_scans stay at their defaults; every other field is unchanged.

Response

Successful Response

actions
V1Action · object[]
required
answers_citing_you
V1Count · object | null
required

A count, what it is out of, and its share in points: null where it is out of nothing.

attribution
Attribution · object | null
required
competitor_rank
V1CompetitorRank · object | null
required

Your rank by Heralded Score among the tracked competitors over the period, on the side read; null while your score or every competitor's is unmeasured, and under lean.

counts
WorkCounts · object
required

Current work populations, excluding setup; your_turn follows the viewer scope.

daily_scans_since_weekly
integer
required
diagnosis
V1Diagnosis · object | null
required

What rivals win over the last week and the drafts ready to answer it; null unless with_diagnosis.

headline
V1Headline · object | null
required
heralded_score
V1Figure · object
required
heralded_score_band
string | null
required

The band of score_bands the Heralded Score falls in; null without a score.

latest_read
V1LatestRead · object | null
required
mentioned
V1Figure · object
required
meta
Meta · object
required

Normalized query and newest included scan.

next_daily_scan_at
string<date-time> | null
required
next_weekly_scan_at
string<date-time> | null
required
open_action_count
integer
required
deprecated

Alias of counts.open.

period
V1Period · object
required
praised
V1Figure · object
required
readiness
V1Readiness · object | null
required

The pages the readiness checks cover: every audited page and the homepage.

report
V1LatestRead · object | null
required

The latest weekly report and its frozen count.

rivals
V1Competitor · object[]
required
score_bands
ScoreBand · object[]
required

Every Heralded Score band, lowest first.

score_context
V1ScoreContext · object | null
required

What the latest weekly scan's score was read from; null before one.

sides
V1Sides · object
required

The Heralded Score, Mentioned and Recommended on each side, whichever side the top-level figures read. A side not measured has a null value.

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
since_started
V1SinceStarted · object | null
required

The Heralded Score's move since the first weekly scan, off the period's figures; null before the first.

source_citation_evidence
enum<string>
default:complete
required
Available options:
complete,
partial,
unavailable
source_unavailable_scans
integer
default:0
required
sources
V1CitedSource · object[]
required
sources_mentioning_you
V1Count · object | null
required

Third-party sites with a read page naming you, out of third-party sites read, over period: the Sources page's sites naming you. Null before the first report and while citation evidence is unavailable.

understood
V1Figure · object
required
verified_actions
V1VerifiedActions · object
required

Delivered work with a verified gain or a cited page, newest result first.