Skip to main content
GET
Get Topics

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

side
enum<string>
default:all

The side whose score orders a topic's winners. The leader uses Heralded Scores; scores always carries all, ai and search.

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
topic
string<uuid> | null

Tracked topic UUID.

prompt
string<uuid> | null

Question id from list_prompts.

limit
integer
default:20

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
period
enum<string>
default:1w

Weekly-report period.

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

Include weekly card figures and their adjacent-window changes.

q
string | null

Text to search for.

Maximum string length: 200
direction
enum<string> | null

Order results ascending or descending.

Available options:
asc,
desc
with_menus
boolean
default:false

Include available filter choices.

url
string | null

The page URL to select.

Maximum string length: 4096
band
enum<string> | null

Filter by the topic score band.

Available options:
Invisible,
Under-visible,
Emerging,
Strong,
Leader,
Not measured
sort
enum<string>
default:demand

Field to order results by.

Available options:
topic,
demand,
rank,
ai_score,
search_score,
cited_pct
view
enum<string>
default:tracked

tracked: the topics read now. suggested: needs Heralded found that the brand does not track. archived: archived topics.

Available options:
tracked,
suggested,
archived

Response

Successful Response

ai_visits_connected
boolean
required
archived_total
integer
default:0
required

Archived topics.

bands
V1TopicBandOption · object[]
required
card_figures
Card Figures · object
required

Weekly card figures and adjacent-window changes when with_trend=true.

cited_share
CitedShare · object
required
competing
integer
default:0
required
leading
integer
default:0
required
limit
integer
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.

offset
integer
required
period
V1Period · object
required
search_connected
boolean
required
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
state
enum<string>
required
Available options:
ready,
awaiting_first_scan,
not_measured
topics
V1Topic · object[]
required
total
integer
required
tracked_total
integer
default:0
required

Topics tracked in a live market and audience.

unanswered_questions
integer
default:0
required