> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Competitor Tools

> Tools to analyze competitors mentioned in AI responses and track their evolution.

## get\_competitors

Get competitors mentioned in AI responses, ranked by mention frequency.

### Parameters

| Parameter      | Type   | Required | Description                                               |
| -------------- | ------ | -------- | --------------------------------------------------------- |
| `brandId`      | string | Yes      | The brand ID                                              |
| `relationship` | string | No       | Filter by type: `SELF`, `DIRECT`, `INDIRECT`, `ECOSYSTEM` |
| `limit`        | number | No       | Max competitors to return (default: 20)                   |

### Relationship Types

| Type        | Description                                |
| ----------- | ------------------------------------------ |
| `SELF`      | Your own brand                             |
| `DIRECT`    | Direct competitors (same product category) |
| `INDIRECT`  | Indirect competitors (adjacent solutions)  |
| `ECOSYSTEM` | Ecosystem players (complementary products) |

### Returns

| Field          | Type   | Description                   |
| -------------- | ------ | ----------------------------- |
| `id`           | string | Competitor domain ID          |
| `name`         | string | Competitor name               |
| `domain`       | string | Competitor's domain           |
| `relationship` | string | Relationship type             |
| `mentions`     | number | Total mention count           |
| `avgPosition`  | number | Average position in responses |
| `avgSentiment` | number | Average sentiment (0-100)     |

### Example Output

```markdown theme={null}
## Competitors for Acme Corp

| Rank | Name | Relationship | Mentions | Avg Position | Sentiment |
|------|------|--------------|----------|--------------|-----------|
| 1 | CompetitorA | DIRECT | 892 | 2.3 | 75/100 |
| 2 | CompetitorB | DIRECT | 654 | 3.1 | 72/100 |
| 3 | Acme Corp | SELF | 612 | 2.8 | 78/100 |
| 4 | CompetitorC | DIRECT | 445 | 4.2 | 68/100 |
| 5 | ToolX | INDIRECT | 234 | 5.1 | 71/100 |
```

### Example Prompts

```
Who are my competitors in AI responses?
```

```
Show me only direct competitors
```

```
Which brands appear alongside mine most often?
```

### 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`       | number | No       | Days to analyze (default: 30)                     |

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

```markdown theme={null}
## 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
```

<Tip>
  Use `get_competitors` first to find the `competitorId` you want to track.
</Tip>

### 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`  | number | No       | Number of days to analyze (default: 30) |

### 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`