Skip to main content
GET
Get Competitor

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.

key
string
required

A competitor key from list_competitors.

Required string length: 1 - 300

Query Parameters

country
string | null

Check country or global. Omit for all.

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

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
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:
lost,
won,
pages,
questions,
work,
website,
changes
with_details
boolean
default:false

Include weekly site changes and how AI describes this brand.

you
enum<string> | null

Keep prompts or answers matching this brand-presence state.

Available options:
named,
not_named
topic_id
string | null

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

Maximum string length: 100
page_url
string | null

Also return this competitor-owned page's details, including daily-only discoveries.

Required string length: 1 - 4096

Response

Successful Response

actions_total
integer
default:0
required

All live work items about this subject before paging.

brand_key
string
required
capacity
RosterPool · object
required

Roster size as a pool (MK-4). cap is None on a workspace with no active subscription to read one off.

citation_evidence
enum<string>
default:complete
required
Available options:
complete,
partial,
unavailable
description
string | null
required

The latest stored AI description.

description_at
string<date-time> | null
required

When the report supplying the AI description completed.

description_scan_id
string<uuid> | null
required

The report whose interpretation supplies the AI description.

domain
string | null
required
engines
CompetitorEngine · object[]
required
figure_changes
Figure Changes · object
required

Each competitor figure’s comparison with the earlier period.

Weekly competitor figure values, including your score less theirs under gap.

figures
Versus · object[]
required
gap_delta
integer | null
required

Change in your score lead, yours less theirs; null when either comparison is unavailable or their baselines differ.

history
V1TrendPoint · object[]
required
is_tracked
boolean
required
lost
VersusPage · object
required

One page of a pane's lost or won prompts, widest gap first, and how many there are.

meta
Meta · object
required

Normalized query and newest included scan.

most_said_against
string | null
required

With details, the negative opinion with the most holders in the period.

most_said_for
string | null
required

With details, the positive opinion with the most holders in the period.

name
string
required
next_step
WorkRowResponse · object | null
required

The highest-priority eligible work item across the subject’s entire live work selection, or null.

pages
CompetitorCitedPage · object[]
required

The most cited rival pages. A floor unless citation_evidence is complete.

pages_total
integer
required

The number of cited rival pages. A floor unless citation_evidence is complete.

paused_engines
string[]
required

The engines paused for the latest report in the period, respecting the engine filter.

period
V1Period · object
required
product_cards
BrandProductCards · object | null
required

Product-card figures for ecommerce brands; null for other brands and Google search.

rival
RivalPagePane · object | null
required
score
ScoreMark · object
required

A score or figure from the figures read, with the band it is coloured by (#4259).

key is the engine or the figure measured. band is the Heralded Score's band for the value, so a mark and a score read on one scale, and "Not measured" where no value is served, which includes a group under the minimum of answers. On a score, answers counts every answer the period read under the filters, including those a figure's own denominator leaves out.

tracked_since
string<date> | null
required
trend
PromptTrend · object
required

A score's change, as the Trend column and the pane state it.

unavailable_scans
integer
default:0
required
versus
Versus · object
required

One figure for the competitor beside the brand's own. gap is yours less theirs; it and lead are null where either side has no value.

website
V1CompetitorSiteDetail · object | null
required

Weekly site data and moves with with_details=true.

won
VersusPage · object
required

One page of a pane's lost or won prompts, widest gap first, and how many there are.

work
WorkRowResponse · object[]
required

One page of live work explicitly about this subject, highest priority first.

focus_selection
Focus · object | null

The brand’s current focus selection and capacity.

moves
V1CompetitorSites · object | null

The first page of stored changes on this competitor’s site.

Example: