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

> Analysez la performance par Topic (keyword).

Liste les Topics avec le nombre de réponses et les indicateurs SELF au niveau des réponses pour le périmètre sélectionné. La route de l’API conserve les noms de champs `keywords` et `keyword` par compatibilité.

<Note>
  Consultez [Entités](/fr/developers/entities#topic) pour la structure complète de l’objet Topic.
</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="tag" type="string">
  Filtre par identifiant de Tag. Accepte plusieurs valeurs séparées par des virgules (par exemple `id1,id2`).
</ParamField>

<ParamField query="limit" type="number" default="50">
  Nombre maximal de Topics 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="prompts">
  Champ de tri : `prompts`, `answers`, `mentionRate`, `shareOfVoice`, `sentiment`, `keyword`
</ParamField>

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

## Réponse

<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 Topics correspondant aux filtres</ResponseField>
    <ResponseField name="count" type="number">Nombre de Topics 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="keywords" type="array">
  <Expandable title="Objet Topic">
    <ResponseField name="id" type="string">Identifiant du Topic</ResponseField>
    <ResponseField name="keyword" type="string">Texte du Topic</ResponseField>
    <ResponseField name="totalPrompts" type="number">Nombre de prompts associés à ce Topic</ResponseField>
    <ResponseField name="totalAnswers" type="number">Réponses enregistrées dans le périmètre sélectionné</ResponseField>
    <ResponseField name="brandMentionRate" type="number">Réponses avec une mention SELF divisées par les réponses avec une mention SELF ou DIRECT</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Occurrences de mentions SELF divisées par les occurrences de mentions SELF et DIRECT</ResponseField>
    <ResponseField name="avgSentiment" type="number">Sentiment moyen des mentions SELF sur une échelle de 0 à 100 ; `0` est renvoyé en l’absence de mention SELF notée</ResponseField>
  </Expandable>
</ResponseField>

## Exemple de requête

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

## Exemple de réponse

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 25,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "keywords": [
    {
      "id": "topic_01",
      "keyword": "data exports",
      "totalPrompts": 15,
      "totalAnswers": 120,
      "brandMentionRate": 45.5,
      "shareOfVoice": 32.1,
      "avgSentiment": 78.3
    },
    {
      "id": "topic_02",
      "keyword": "analytics integrations",
      "totalPrompts": 8,
      "totalAnswers": 64,
      "brandMentionRate": 28.1,
      "shareOfVoice": 18.5,
      "avgSentiment": 72.0
    }
  ]
}
```

## Erreurs

| Statut | Code | Description |
| - | - | - |
| 401 | erreur de passerelle | Jeton d’API manquant ou invalide |
| 404 | `BRAND_NOT_FOUND` | Marque inexistante ou inaccessible |
| 429 | erreur de passerelle | 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.