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

# Obtenir l’instantané de performance

> Lisez les indicateurs de mention, de citation, de sentiment et de part de voix d’une marque au niveau des réponses.

Renvoie les indicateurs au niveau des réponses pour le périmètre sélectionné, ainsi que les ventilations par Topic, Tag, concurrent et source.

<Note>
  Cet endpoint renvoie des indicateurs agrégés. Consultez [Competitor](/fr/developers/entities#competitor) et [Source](/fr/developers/entities#source) pour les structures utilisées dans `topCompetitors` et `topSources`.
</Note>

## Formules des indicateurs

Comprendre le calcul des indicateurs est indispensable pour reproduire les résultats :

| Indicateur | Formule | Détails |
| - | - | - |
| **Taux de mention** | `mentionCount / mentionTotal × 100` | `mentionCount` est le nombre de réponses avec une mention SELF. `mentionTotal` est le nombre de réponses avec au moins une mention SELF ou DIRECT. |
| **Couverture** | `mentionCount / responsesTotal × 100` | Couverture au niveau des réponses : réponses avec une mention SELF divisées par toutes les réponses du périmètre sélectionné. Ce n’est pas la couverture au niveau des prompts. |
| **Taux de citation** | `sourceCount / sourceTotal × 100` | `sourceCount` est le nombre de réponses avec une citation SELF. `sourceTotal` est le nombre de réponses avec au moins une citation SELF ou DIRECT. |
| **Part de voix** | `sovSelf / sovTotal × 100` | Occurrences de mentions SELF divisées par les occurrences de mentions SELF et DIRECT. Les mentions INDIRECT sont exclues. |

<Warning>
  Le taux de mention et la couverture ont des dénominateurs différents. La réponse expose `mentionCount`, `mentionTotal` et `responsesTotal`, mais pas `sovSelf` ni `sovTotal`.
</Warning>

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

```http theme={null}
GET /api/v1/brands/{brandId}/performance
```

## 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 dans l’instantané. 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>

<Warning>
  Utilisez un seul mode de dates par requête. Combiner `period` avec une paire de dates personnalisées complète peut faire diverger le filtre appliqué des métadonnées `period` renvoyées.
</Warning>

<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 (keywordId). 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>

## Réponse

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

<ResponseField name="brand" type="object">
  <Expandable title="Informations de la marque">
    <ResponseField name="id" type="string">Identifiant de la marque</ResponseField>
    <ResponseField name="name" type="string">Nom de la marque</ResponseField>
    <ResponseField name="domain" type="string">Domaine principal</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="period" type="object">
  <Expandable title="Informations de période">
    <ResponseField name="start" type="string">Date de début (ISO 8601)</ResponseField>
    <ResponseField name="end" type="string">Date de fin (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="methodology" type="object">
  <Expandable title="Détail de la méthodologie">
    <ResponseField name="promptsCount" type="number">Nombre total de prompts analysés</ResponseField>
    <ResponseField name="providersCount" type="number">Nombre de fournisseurs IA</ResponseField>
    <ResponseField name="providers" type="array">Liste des identifiants de fournisseurs (par exemple `openai`, `perplexity`)</ResponseField>
    <ResponseField name="responsesTotal" type="number">Réponses enregistrées dans le périmètre sélectionné</ResponseField>
    <ResponseField name="responsesWithMentions" type="number">Réponses contenant au moins une mention SELF ou DIRECT</ResponseField>
    <ResponseField name="responsesWithSources" type="number">Réponses contenant au moins une citation SELF ou DIRECT</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="scores" type="object">
  <Expandable title="Scores de performance">
    <ResponseField name="mentionRate" type="number">Taux de mention de la marque (%)</ResponseField>
    <ResponseField name="mentionCount" type="number">Nombre de réponses où votre marque (SELF) est mentionnée</ResponseField>
    <ResponseField name="mentionTotal" type="number">Nombre de réponses contenant **au moins une mention SELF ou d’un concurrent DIRECT**. C’est le dénominateur de `mentionRate` : ce n’est PAS le nombre total de réponses. Les mentions INDIRECT sont exclues.</ResponseField>
    <ResponseField name="coverage" type="number">Couverture de la marque (%). Part de toutes les réponses suivies où votre marque est mentionnée. Formule : `mentionCount / responsesTotal × 100`.</ResponseField>
    <ResponseField name="sourceRate" type="number">Taux de citation comme source (%)</ResponseField>
    <ResponseField name="sourceCount" type="number">Nombre de réponses distinctes contenant une citation SELF</ResponseField>
    <ResponseField name="sourceTotal" type="number">Nombre de réponses contenant **au moins une citation de source SELF ou DIRECT**. C’est le dénominateur de `sourceRate` : ce n’est PAS le nombre total de réponses. Les sources INDIRECT sont exclues.</ResponseField>
    <ResponseField name="sourcePages" type="number">Nombre d’URL distinctes de votre domaine (SELF) citées comme sources dans l’ensemble des réponses IA.</ResponseField>
    <ResponseField name="sentiment" type="number">Sentiment moyen des mentions SELF sur une échelle de 0 à 100 ; `0` est aussi renvoyé en l’absence de mention SELF notée</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Part de voix (%). Formule : mentions SELF / (mentions SELF + DIRECT) × 100. Les mentions INDIRECT sont exclues.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topCompetitors" type="array">
  Principaux concurrents par nombre de mentions
</ResponseField>

<ResponseField name="topSources" type="array">
  Principales sources par nombre de citations
</ResponseField>

<ResponseField name="byTopic" type="array">
  <Expandable title="Objet de ventilation par Topic">
    <ResponseField name="id" type="string">Identifiant du Topic</ResponseField>
    <ResponseField name="topic" type="string">Nom du Topic</ResponseField>
    <ResponseField name="score" type="number">Score composite (0 à 100). Formule : `mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2`.</ResponseField>
    <ResponseField name="mentionRate" type="number">Taux de mention pour ce Topic (%). Formule : `selfMentionAnswers / responsesWithMentions × 100`, où `responsesWithMentions` compte les réponses de ce Topic avec au moins une mention SELF ou d’un concurrent DIRECT. Même dénominateur que `scores.mentionRate` au premier niveau.</ResponseField>
    <ResponseField name="sourceRate" type="number">Taux de citation pour ce Topic (%). Formule : `selfSourceAnswers / responsesWithSources × 100`, où `responsesWithSources` compte les réponses de ce Topic avec au moins une citation de source SELF ou DIRECT. Même dénominateur que `scores.sourceRate` au premier niveau (INDIRECT exclu).</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Part de voix pour ce Topic (%). Formule : mentions SELF du Topic / (mentions SELF + DIRECT du Topic) × 100.</ResponseField>
    <ResponseField name="avgSentiment" type="number">Score de sentiment moyen des mentions de la marque dans ce Topic (null sans mention)</ResponseField>
    <ResponseField name="promptsCount" type="number">Nombre de prompts distincts dans ce Topic</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="byTag" type="array">
  <Expandable title="Objet de ventilation par Tag">
    <ResponseField name="id" type="string">Identifiant du Tag</ResponseField>
    <ResponseField name="name" type="string">Nom du Tag</ResponseField>
    <ResponseField name="score" type="number">Score composite (0 à 100). Formule : `mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2`.</ResponseField>
    <ResponseField name="mentionRate" type="number">Taux de mention pour ce Tag (%). Formule : `selfMentionAnswers / responsesWithMentions × 100`, où `responsesWithMentions` compte les réponses de ce Tag avec au moins une mention SELF ou d’un concurrent DIRECT. Même dénominateur que `scores.mentionRate` au premier niveau.</ResponseField>
    <ResponseField name="sourceRate" type="number">Taux de citation pour ce Tag (%). Formule : `selfSourceAnswers / responsesWithSources × 100`, où `responsesWithSources` compte les réponses de ce Tag avec au moins une citation de source SELF ou DIRECT. Même dénominateur que `scores.sourceRate` au premier niveau (INDIRECT exclu).</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Part de voix pour ce Tag (%). Formule : mentions SELF du Tag / (mentions SELF + DIRECT du Tag) × 100.</ResponseField>
    <ResponseField name="avgSentiment" type="number">Score de sentiment moyen des mentions de la marque dans ce Tag (null sans mention)</ResponseField>
    <ResponseField name="promptsCount" type="number">Nombre de prompts distincts dans ce Tag</ResponseField>
  </Expandable>
</ResponseField>

## Exemple de requête

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

## Exemple de réponse

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "brand_01",
    "name": "Acme Analytics",
    "domain": "acme.example"
  },
  "period": {
    "start": "2026-07-01",
    "end": "2026-07-31"
  },
  "methodology": {
    "promptsCount": 156,
    "providersCount": 2,
    "providers": ["openai", "perplexity"],
    "responsesTotal": 312,
    "responsesWithMentions": 230,
    "responsesWithSources": 184
  },
  "scores": {
    "mentionRate": 45.2,
    "mentionCount": 104,
    "mentionTotal": 230,
    "coverage": 33.33,
    "sourceRate": 23.9,
    "sourceCount": 44,
    "sourceTotal": 184,
    "sourcePages": 27,
    "sentiment": 78.1,
    "shareOfVoice": 8.13
  },
  "topCompetitors": [
    {
      "id": "competitor_01",
      "name": "Rival Labs",
      "relationship": "DIRECT",
      "mentions": 111,
      "avgPosition": 2.3,
      "avgSentiment": 75.2
    }
  ],
  "topSources": [
    {
      "id": "source_01",
      "domain": "publisher.example",
      "mentions": 102,
      "avgPosition": 3.1,
      "isSelf": false
    }
  ],
  "byTopic": [
    {
      "id": "topic_01",
      "topic": "Data exports",
      "score": 68,
      "mentionRate": 67.50,
      "sourceRate": 28.00,
      "shareOfVoice": 9.44,
      "avgSentiment": 76.3,
      "promptsCount": 12
    }
  ],
  "byTag": [
    {
      "id": "tag_01",
      "name": "comparison",
      "score": 72,
      "mentionRate": 55.00,
      "sourceRate": 30.00,
      "shareOfVoice": 10.25,
      "avgSentiment": 81.5,
      "promptsCount": 8
    }
  ]
}
```

## Erreurs

| Statut | Code | Description |
| - | - | - |
| 400 | `INVALID_PARAMETER` | Paramètre de requête invalide |
| 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.