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

# List Competitors

> Track competitor mentions, share of voice, and positioning

Monitor how your brand and competitors are mentioned in AI responses. Competitors have three relationship types: `SELF` (your brand), `DIRECT` (direct competitors), and `INDIRECT` (indirect competitors). The list and evolution endpoints return only `SELF` and `DIRECT` by default. Share of Voice is calculated using only `SELF` and `DIRECT` mentions.

<Note>
  See [Entities](/developers/entities#competitor) for the complete Competitor object structure.
</Note>

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

### Path Parameters

<ParamField path="brandId" type="string" required>
  The unique identifier of the brand
</ParamField>

### Query Parameters

<ParamField query="period" type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField query="startDate" type="string">
  Start date (ISO 8601 format)
</ParamField>

<ParamField query="endDate" type="string">
  End date (ISO 8601 format)
</ParamField>

<ParamField query="provider" type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField query="topic" type="string">
  Filter by topic ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField query="tag" type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField query="type" type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

<ParamField query="relationship" type="string" default="SELF,DIRECT">
  Filter by relationship type. Supports comma-separated multi-select: `SELF`, `DIRECT`, `INDIRECT`. Default: `SELF,DIRECT`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of results to return (max: 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of results to skip for pagination
</ParamField>

<ParamField query="sort" type="string" default="mentions">
  Field to sort by: `mentions`, `position`, `sentiment`, `shareOfVoice`, `name`
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort order: `asc` or `desc`
</ParamField>

### Response

Returns competitors with relationship `SELF` (your brand) and `DIRECT` (direct competitors). `INDIRECT` competitors are not included by default.

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of competitors matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of competitors in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="competitors" type="array">
  <Expandable title="Competitor object">
    <ResponseField name="id" type="string">Competitor ID</ResponseField>
    <ResponseField name="name" type="string">Competitor name</ResponseField>
    <ResponseField name="domain" type="string">Competitor domain</ResponseField>

    <ResponseField name="relationship" type="string">
      `SELF` (your brand) or `DIRECT` (competitor)
    </ResponseField>

    <ResponseField name="totalMentions" type="number">Total mentions count</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Share of voice (%)</ResponseField>
    <ResponseField name="avgPosition" type="number">Average position in responses</ResponseField>
    <ResponseField name="avgSentiment" type="number">Average sentiment score (0-100)</ResponseField>
  </Expandable>
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/competitors?limit=10&offset=0" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

### Example Response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 10,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "competitors": [
    {
      "id": "cmp1",
      "name": "My Brand",
      "domain": "mybrand.com",
      "relationship": "SELF",
      "totalMentions": 104,
      "shareOfVoice": 8.13,
      "avgPosition": 2.1,
      "avgSentiment": 78.1
    },
    {
      "id": "cmp2",
      "name": "Competitor A",
      "domain": "competitor-a.com",
      "relationship": "DIRECT",
      "totalMentions": 111,
      "shareOfVoice": 8.73,
      "avgPosition": 1.8,
      "avgSentiment": 75.2
    }
  ]
}
```