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

# Lister les concurrents

> Suivez les mentions, la part de voix et le positionnement des concurrents.

Liste les domaines concurrents et leurs indicateurs de mention pour le périmètre sélectionné. L’ensemble de relations par défaut est `SELF,DIRECT` ; ajoutez `INDIRECT` explicitement si nécessaire. Sur cet endpoint, la part de voix utilise les occurrences de mentions de l’ensemble de relations sélectionné.

<Note>
  Consultez [Entités](/fr/developers/entities#competitor) pour la structure complète de l’objet Competitor.
</Note>

<ParamField header="Authorization" type="string" required>
  Jeton bearer. Exemple : `Bearer qw-api-xxx`
</ParamField>

## Paramètres de chemin

<ParamField path="brandId" type="string" required>
  L’identifiant unique de la marque
</ParamField>

## Paramètres de requête

<ParamField query="period" type="number">
  Nombre de jours à inclure. Sans valeur, toutes les données sont renvoyées.
</ParamField>

<ParamField query="startDate" type="string">
  Date de début au format `YYYY-MM-DD`. Fournissez-la avec `endDate` ; une borne seule est actuellement ignorée. Choisissez soit `period`, soit la paire de dates complète.
</ParamField>

<ParamField query="endDate" type="string">
  Date de fin au format `YYYY-MM-DD`. Fournissez-la avec `startDate` ; une borne seule est actuellement ignorée. Ne combinez pas la paire de dates complète avec `period`.
</ParamField>

<ParamField query="provider" type="string">
  Filtre par fournisseur IA. Accepte plusieurs valeurs séparées par des virgules (par exemple `chatgpt,claude`).
</ParamField>

<ParamField query="topic" type="string">
  Filtre par identifiant de Topic. Accepte plusieurs valeurs séparées par des virgules (par exemple `id1,id2`).
</ParamField>

<ParamField query="tag" type="string">
  Filtre par identifiant de Tag. Accepte plusieurs valeurs séparées par des virgules (par exemple `id1,id2`).
</ParamField>

<ParamField query="type" type="string">
  Filtre par type de prompt : `TOFU`, `MOFU`, `BOFU` ou `POST_PURCHASE`
</ParamField>

<ParamField query="relationship" type="string" default="SELF,DIRECT">
  Filtre par type de relation. Accepte plusieurs valeurs séparées par des virgules : `SELF`, `DIRECT`, `INDIRECT`. Par défaut : `SELF,DIRECT`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Nombre maximal de résultats renvoyés (maximum : 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Nombre de résultats à ignorer pour la pagination
</ParamField>

<ParamField query="sort" type="string" default="mentions">
  Champ de tri : `mentions`, `position`, `sentiment`, `shareOfVoice`, `name`
</ParamField>

<ParamField query="order" type="string" default="desc">
  Ordre de tri : `asc` ou `desc`
</ParamField>

## Réponse

Renvoie les concurrents du filtre de relation demandé. `INDIRECT` n’est exclu que par le filtre par défaut.

<ResponseField name="success" type="boolean">
  Indique si la requête a réussi
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Informations de pagination">
    <ResponseField name="total" type="number">Nombre total de concurrents correspondant aux filtres</ResponseField>
    <ResponseField name="count" type="number">Nombre de concurrents dans cette réponse</ResponseField>
    <ResponseField name="limit" type="number">Nombre maximal d’éléments par page</ResponseField>
    <ResponseField name="offset" type="number">Nombre d’éléments ignorés</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="competitors" type="array">
  <Expandable title="Objet Competitor">
    <ResponseField name="id" type="string">Identifiant du concurrent</ResponseField>
    <ResponseField name="name" type="string">Nom du concurrent</ResponseField>
    <ResponseField name="domain" type="string">Domaine du concurrent</ResponseField>

    <ResponseField name="relationship" type="string">
      `SELF`, `DIRECT` ou `INDIRECT`, selon le filtre `relationship`
    </ResponseField>

    <ResponseField name="totalMentions" type="number">Nombre total de mentions</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Occurrences de mentions de cette ligne divisées par toutes les occurrences de mentions de l’ensemble de relations sélectionné</ResponseField>
    <ResponseField name="avgPosition" type="number">Position moyenne dans les réponses</ResponseField>
    <ResponseField name="avgSentiment" type="number | null">Sentiment moyen des mentions sur une échelle de 0 à 100, ou `null`</ResponseField>
  </Expandable>
</ResponseField>

## Exemple de requête

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/competitors?limit=10&offset=0" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Exemple de réponse

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 10,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "competitors": [
    {
      "id": "competitor_self",
      "name": "Acme Analytics",
      "domain": "acme.example",
      "relationship": "SELF",
      "totalMentions": 104,
      "shareOfVoice": 8.13,
      "avgPosition": 2.1,
      "avgSentiment": 78.1
    },
    {
      "id": "competitor_01",
      "name": "Rival Labs",
      "domain": "rival.example",
      "relationship": "DIRECT",
      "totalMentions": 111,
      "shareOfVoice": 8.73,
      "avgPosition": 1.8,
      "avgSentiment": 75.2
    }
  ]
}
```

## Erreurs

| Statut | Signification |
| - | - |
| `400` | Paramètre de requête ou filtre de relation invalide |
| `401` | Jeton d’API manquant ou invalide |
| `404` | Marque introuvable ou inaccessible |
| `429` | Limite de débit dépassée ; respectez `Retry-After` |

Consultez [Limites de débit](/fr/developers/rate-limits) pour la gestion des nouvelles tentatives.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.