Skip to main content
GET
Get Competitors

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: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
with_details
boolean
default:false

Include the page, weekly competitor sites and moves, and AI descriptions.

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
with_page
boolean
default:false

Include competitor website details.

with_menus
boolean
default:false

Include available filter choices.

with_trend
boolean
default:true

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

sort
enum<string> | null

Order the leaderboard by this figure. Defaults to Mentioned descending on Search, or Heralded Score descending on AI and All.

Available options:
brand,
score,
trend,
mentioned,
recommended,
product_cards
direction
enum<string> | null

Order results ascending or descending.

Available options:
asc,
desc
discovered_limit
integer
default:10

Maximum discovered competitors to return.

Required range: 1 <= x <= 100
discovered_offset
integer
default:0

Discovered competitors to skip.

Required range: x >= 0

Response

Successful Response

channels
V1Channel · object[]
required
competitors
V1Competitor · object[]
required
description_at
string<date-time> | null
required

When the report supplying the AI descriptions completed.

description_scan_id
string<uuid> | null
required

The report whose interpretation supplies the AI descriptions.

discovered
V1DiscoveredCompetitor · object[]
required
headline
string | null
required

With details, the templated headline over the filtered leaderboard.

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.

page
CompetitorsPage · object | null
required
period
V1Period · object
required
share_of_voice
V1ShareOfVoice · object
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
sites
V1CompetitorSites · object | null
required

Weekly site data and moves with with_details=true.

Example: