Skip to main content
GET
Get Topic

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.

topic_id
string
required

Select a topic by id, or untagged for prompts without a topic.

Query Parameters

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
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.

period
enum<string>
default:1w

Weekly-report period.

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

Return bounded section previews.

section
enum<string> | null

The section paged by limit and offset.

Available options:
questions,
unanswered,
own_pages,
pages,
brands,
segments,
engines,
keywords,
work
with_pane
boolean
default:false

Add the topic's scores per engine, its Mentioned and Recommended answer counts, its Search trend, its keywords in Google's top 10, its brands and its page total, as by_engine, ai_counts, search_trend, keywords_top10, brands, brands_total and pages_total.

Response

Successful Response

actions
V1TopicNeedAction · object[] | null
required

A suggested topic only.

actions_total
integer
default:0
required

Every live action about this subject, before the list is cut.

adds
V1TopicAdds · object | null
required

What tracking a suggested topic adds. Null until it is tracked: its prompts and keywords are drafted then.

ai_score_series
FigurePoint · object[]
required
archived_at
string<date-time> | null
required

When the topic was archived; null unless archived.

audience
string
default:All buyers
required

The audience's name, or All buyers.

audience_id
string<uuid> | null
required

Audience UUID; null for All buyers.

band
enum<string>
default:Not measured
required
Available options:
Invisible,
Under-visible,
Emerging,
Strong,
Leader,
Not measured
best_to_track
boolean
required
citation_evidence
enum<string>
default:complete
required
Available options:
complete,
partial,
unavailable
cited_share
CitedShare · object
required
coverage
enum<string> | null
required

A suggested topic only: whether a page of the brand's answers it.

Available options:
covered,
weak,
missing,
unchecked,
uncovered,
unknown
coverage_questions
TopicQuestionResult · object[]
required
demand
integer | null
required
demand_countries
TopicCountryDemand · object[]
required

Per-country monthly keyword totals for tracked topics; empty on suggestions.

demand_measured
boolean | null
required

A suggested topic only.

engines
string[]
required

The engines selected for this topic.

english_name_suggestion
EnglishTopicName · object | null
required

The cached English name offered for member acceptance.

evidence
V1TopicEvidence · object[] | null
required

What led to a suggested topic: its searches and questions, with counts, then the questions members added to it. Null on a tracked topic.

first_answers_at
string<date-time> | null
required

The first answered time, or the estimate while its prompt read is pending. Null when no estimate is available.

first_score_on
string<date> | null
required

The next weekly report's date for the market. Null before the brand has a weekly schedule.

id
string
required

The tracked-topic UUID, or s:{id} for a suggestion. Use it in topics/{id}.

keyword_research
V1TopicKeywordResearch · object[]
required

Whether keyword research found none or was unavailable for this topic.

keywords
V1TopicKeyword · object[]
required

Its active and paused keywords.

keywords_count
integer
required

Keywords tracked in this topic.

leader
V1TopicLeader · object | null
required

The brand that clearly leads on AI; null without a clear leader.

leader_state
enum<string>
default:not_measured
required

measured: one brand clearly leads and leader names it. no_clear_leader: your Heralded Score is measured but no brand clearly leads. not_measured: your Heralded Score is not measured.

Available options:
measured,
no_clear_leader,
not_measured
live_actions
V1Action · object[]
required

The live actions about this topic, highest priority first.

market
string
default:global
required

The topic's market: country ISO code, europe or global.

measurement_status
enum<string>
default:new
required

New until a subscription weekly report scores it, then measured. Independent of tracking state.

Available options:
new,
measured
meta
Meta · object
required

Normalized query and newest included scan.

need
string | null
required

The buyer need the topic is for, in a sentence.

next_step
V1Action · object | null
required

The action next_step_action_id names, in the same shape as actions.

next_step_action_id
string<uuid> | null
required

The highest-priority live action that awaits a member and whose verb the reader may press; null when there is none.

own_pages
TopicOwnPage · object[]
required
pages
V1TopicCitedPage · object[]
required

The pages its prompts cite most. Google ranks join them with the search side.

period
V1Period · object
required
prompts
V1TopicPrompt · object[]
required
prompts_count
integer
required

Prompts tracked in this topic.

prompts_filtered
integer
default:0
required
prompts_total
integer
required

All prompts matching this selection before paging.

scores
TopicScores · object | null
required

The topic's Heralded Score on all, ai and search, each with its band, change, Mentioned and Recommended; null on a suggested topic. A side with no reading has a null value.

search_term
string | null
required

The topic's retained local search term.

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:
tracked,
suggested,
archived
suggestion_id
string<uuid> | null
required

The suggestion to track; null for a tracked topic.

topic
string
required
tracked_topic_id
string<uuid> | null
required

The tracked-topic identity, fixed to one market and audience.

unanswered_questions
integer
default:0
required
unavailable_scans
integer
default:0
required
volume_partial
boolean
default:false
required

True when any tracked keyword or country has unknown volume.

why_labels
string[]
required

Why a suggested topic is suggested.

winners
TopicStanding · object[]
required

The brand and its rivals, best score on the topic on side first; at most five.

ai_counts
V1TopicAiCounts · object | null

Only with with_pane. How many AI answers mention you and how many recommend you, each over the answers it is counted over: the numerator, denominator and answers that figures.mentioned and figures.recommended carry for the same period and filters.

answered_questions
integer | null

Questions the topic’s own pages answer under the selection; unknown questions are excluded.

brands
V1TopicBrand · object[] | null

Only with with_pane. The first five of the brand and its rivals, best on side first, by Mentioned on search. When you rank lower than fifth, you take the fifth place.

brands_total
integer | null

Only with with_pane. All brands ranked on the topic, you included.

by_engine
V1ScoreRow · object[] | null

Only with with_pane. The topic's figures on each AI engine that answered in the period, in the engines' order: the rows scores serves with group_by=engine and topic, under the request's filters except engine.

focus_selection
Focus · object | null

The brand’s current focus selection and capacity.

keywords_top10
integer | null

Only with with_pane. How many of its active and paused keywords have one of your pages in the ten results of their latest check. keywords_count is the total.

own_pages_total
integer | null

All own pages serving this topic before paging.

pages_total
integer | null

Only with with_pane. All pages its prompts cite, before pages cuts them.

pane_figures
V1SideFigures · object | null

The selected side’s figure values, comparisons and small weekly trends.

paused_engines
string[] | null

Only with with_pane. The engines paused for the latest report in the period, in registry order. Like by_engine, this list ignores the engine filter.

search_trend
V1TrendPoint · object[] | null

Only with with_pane. Mentioned on the Search side per weekly report, as scores trends it. Empty when no report checked the topic's keywords.