Competitor tools

See Filter Compatibility for the authoritative global evidence-filter contract. Those shared parameters apply in addition to the tool-specific parameters shown below.

get_competitors

Rank competitors by mentions in an evidence scope. The tool returns all-time results when no window is supplied; use a rolling period or inclusive custom dates, optionally combined with one topic and/or tag.

Parameters

Parameter	Type	Required	Description
`brandId`	string	Yes	The brand ID
`relationship`	string	No	`SELF`, `DIRECT`, `INDIRECT`, `ECOSYSTEM`, `COMPLEMENTARY`, or `SELF_DIRECT`
`period`	integer or string	No	Rolling days (1-3650), `"all"`, or `"custom"` with dates; omit for all-time
`startDate`	string	No	Inclusive start date (`YYYY-MM-DD`); provide with `endDate`
`endDate`	string	No	Inclusive end date (`YYYY-MM-DD`); provide with `startDate`
`provider`	string	No	Legacy single-provider or model alias
`providers`	string[]	No	AI provider or model IDs; values are ORed
`topic` / `topicId`	string	No	Single-topic aliases using a UUID returned by `list_topics`
`topicIds`	string[]	No	Topic UUIDs; values are ORed
`tag` / `tagId`	string	No	Single-tag aliases using a UUID returned by `list_tags`
`tagIds`	string[]	No	Tag UUIDs; values are ORed
`funnelStages`	string[]	No	Any of `TOFU`, `MOFU`, and `BOFU`; values are ORed
`limit`	integer	No	Max competitors to return (default: 20, max: 100)

Relationship types

Type	Description
`SELF`	Your own brand
`DIRECT`	Direct competitors (same product category)
`INDIRECT`	Indirect competitors (adjacent solutions)
`ECOSYSTEM`	Ecosystem players (complementary products)
`COMPLEMENTARY`	Complementary products or services
`SELF_DIRECT`	Your brand and its direct competitors in one ranking

Returns

Field	Type	Description
`brandName`	string	Monitored brand name
`appliedFilters`	object	Resolved evidence window and taxonomy filters used for the ranking
`competitors[].id`	string	Competitor domain ID
`competitors[].name`	string	Competitor name
`competitors[].domain`	string or null	Competitor’s domain
`competitors[].relationship`	string	Relationship type
`competitors[].mentions`	number	Mention count inside the requested evidence scope
`competitors[].uniqueAnswers` / `uniqueQuestions`	number	Distinct answers and monitored questions contributing mentions
`competitors[].shareOfVoice`	number or null	Share of SELF + DIRECT mentions in scope; null for other relationships
`competitors[].shareOfResponses` / `mentionRate`	number or null	Response-level visibility rates when available
`competitors[].avgPosition`	number or null	Average position in responses inside the requested scope
`competitors[].avgSentiment`	number or null	Average sentiment (0-100)
`competitors[].providers`	string[]	Providers contributing evidence for the competitor

Example output

## Competitors for Acme Corp

| Rank | Name | Relationship | Mentions | Share of Voice | Avg Position | Sentiment | Competitor Domain ID |
|------|------|--------------|----------|----------------|--------------|-----------|----------------------|
| 1 | CompetitorA | DIRECT | 892 | 34.26% | 2.3 | 75/100 | 11111111-1111-4111-8111-111111111111 |
| 2 | CompetitorB | DIRECT | 654 | 25.11% | 3.1 | 72/100 | 22222222-2222-4222-8222-222222222222 |
| 3 | Acme Corp | SELF | 612 | 23.50% | 2.8 | 78/100 | 33333333-3333-4333-8333-333333333333 |
| 4 | CompetitorC | DIRECT | 445 | 17.09% | 4.2 | 68/100 | 44444444-4444-4444-8444-444444444444 |
| 5 | ToolX | INDIRECT | 234 | - | 5.1 | 71/100 | 55555555-5555-4555-8555-555555555555 |

Example prompts

Who are my competitors in AI responses?

Show me only direct competitors

Which brands appear alongside mine most often?

Rank my brand and direct competitors for this tag over the last 30 days

OAuth scope

Requires: read:competitors

get_competitor_evolution

Track how a competitor’s presence changes over time: mentions, position, and sentiment trends.

Parameters

Parameter	Type	Required	Description
`brandId`	string	Yes	The brand ID
`competitorId`	string	Yes	The competitor domain ID (from `get_competitors`)
`period`	integer or string	No	Global evidence window; defaults to 30 days
`groupBy`	string	No	`day` (default) or `week`

Returns

Array of daily data points:

Field	Type	Description
`date`	string	Date (YYYY-MM-DD)
`mentions`	number	Mentions on that day
`avgPosition`	number	Average position
`avgSentiment`	number	Average sentiment

Example output

## CompetitorA - Evolution Over Time

Relationship: DIRECT

| Date | Mentions | Avg Position | Sentiment |
|------|----------|--------------|-----------|
| 2025-01-21 | 28 | 2.5 | 73/100 |
| 2025-01-22 | 31 | 2.3 | 74/100 |
| 2025-01-23 | 35 | 2.1 | 76/100 |
| 2025-01-24 | 29 | 2.4 | 75/100 |
| 2025-01-25 | 38 | 2.0 | 77/100 |

Example prompts

How has CompetitorA trended over the last month?

Is CompetitorB gaining or losing visibility?

Show me the evolution of my own brand mentions

Use get_competitors first to find the competitorId you want to track.

OAuth scope

Requires: read:competitors

get_competitor_comparison

Head-to-head comparison of the brand against its top direct competitors: your own stats, your market rank, the top competitors’ stats, a per-competitor win/loss summary on mention count, and the biggest perceived threat.

Parameters

Parameter	Type	Required	Description
`brandId`	string	Yes	The brand ID from `list_brands`
`period`	integer or string	No	Global evidence window; defaults to 30 days
`competitorIds`	string[]	No	Restrict the comparison to 1-10 Competitor Domain IDs

Returns

Field	Description
`period` / `periodLabel`	The analyzed window
`yourStats`	Your brand: `name`, `mentionCount`, `avgSentiment`, `avgPosition` (null if not mentioned in the period)
`marketRank`	Your rank across SELF + DIRECT brands by mention count
`totalCompetitors`	Number of direct competitors found
`topCompetitors[]`	Per competitor: `name`, `domain`, `mentionCount`, `avgSentiment`, `avgPosition`
`headToHead[]`	Top 5 matchups: `competitor`, `yourMentions`, `theirMentions`, `winner` (you/them/tie), plus your vs their sentiment and position
`insights`	`winsAgainstTop5`, `lossesAgainstTop5`, `biggestThreat`

Example prompts

How do I compare to my top competitors right now?

Which competitors am I beating, and which are beating me?

OAuth scope

Requires: read:competitors

Get started

Tool reference

Examples

Workflows

get_competitors

Parameters

Relationship types

Returns

Example output

Example prompts

OAuth scope

get_competitor_evolution

Parameters

Returns

Example output

Example prompts

OAuth scope

get_competitor_comparison

Parameters

Returns

Example prompts

OAuth scope

​get_competitors

​Parameters

​Relationship types

​Returns

​Example output

​Example prompts

​OAuth scope

​get_competitor_evolution

​Parameters

​Returns

​Example output

​Example prompts

​OAuth scope

​get_competitor_comparison

​Parameters

​Returns

​Example prompts

​OAuth scope

get_competitors

Parameters

Relationship types

Returns

Example output

Example prompts

OAuth scope

get_competitor_evolution

Parameters

Returns

Example output

Example prompts

OAuth scope

get_competitor_comparison

Parameters

Returns

Example prompts

OAuth scope