> ## 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 instantanés de perception

> Listez les instantanés mensuels de perception terminés, avec scores, tendances, moyennes et historique.

Renvoie les instantanés de perception terminés, enregistrés par mois. Chaque instantané peut contenir quatre scores de `0-100` : sentiment, alignement, cohérence et alignement factuel. Un score peut valoir `null` s’il n’a pas été calculé.

<Note>
  Il n’y a pas de filtre `period` en jours. Utilisez `months` pour régler la profondeur de l’historique. `nextAnalysisDate` est déduit du mois du dernier instantané ; ce n’est pas une garantie de livraison.
</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="months" type="number" default="12">
  Nombre de mois d’historique à inclure (maximum : 24). Seuls les instantanés `COMPLETED` sont renvoyés.
</ParamField>

## Réponse

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

<ResponseField name="brand" type="object">
  <Expandable title="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 de la marque</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current" type="object">
  Dernier instantané terminé, ou `null` s’il n’y en a pas. Contient `snapshotId`, `month`, `year`, `completedAt` et un objet `scores` avec `sentiment`, `alignment`, `consistency`, `factualAlignment` (chacun de `0-100` ou `null`).
</ResponseField>

<ResponseField name="previous" type="object">
  Instantané terminé précédent, de même forme que `current`, ou `null`.
</ResponseField>

<ResponseField name="trends" type="object">
  Écart (actuel − précédent) pour chaque score : `sentiment`, `alignment`, `consistency`, `factualAlignment`. Une valeur vaut `null` si l’un des deux termes manque.
</ResponseField>

<ResponseField name="averages" type="object">
  Moyenne de chaque score sur l’historique renvoyé (`null` sans point de données).
</ResponseField>

<ResponseField name="history" type="array">
  <Expandable title="Point d’historique">
    <ResponseField name="snapshotId" type="string">Identifiant de l’instantané (à utiliser avec l’endpoint de détail)</ResponseField>
    <ResponseField name="month" type="number">Mois (1 à 12)</ResponseField>
    <ResponseField name="year" type="number">Année</ResponseField>
    <ResponseField name="label" type="string">Libellé `MM/YYYY`</ResponseField>
    <ResponseField name="scores" type="object">`sentiment`, `alignment`, `consistency`, `factualAlignment`</ResponseField>
    <ResponseField name="completedAt" type="string">Horodatage de fin (ISO 8601) ou `null`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  `months` (fenêtre demandée) et `dataPoints` (nombre d’instantanés renvoyés).
</ResponseField>

<ResponseField name="nextAnalysisDate" type="string">
  Premier jour du mois suivant le dernier instantané, ou mois civil suivant s’il n’existe aucun instantané. C’est une date ISO 8601 calculée, pas un engagement de livraison.
</ResponseField>

## Exemple de requête

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/perception?months=6" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Exemple de réponse

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "cm1234567890abcdef",
    "name": "Northstar Labs",
    "domain": "northstar.example"
  },
  "current": {
    "snapshotId": "snap_2026_05",
    "month": 5,
    "year": 2026,
    "scores": {
      "sentiment": 78,
      "alignment": 65,
      "consistency": 82,
      "factualAlignment": 71
    },
    "completedAt": "2026-05-03T04:12:00.000Z"
  },
  "previous": {
    "snapshotId": "snap_2026_04",
    "month": 4,
    "year": 2026,
    "scores": {
      "sentiment": 74,
      "alignment": 61,
      "consistency": 80,
      "factualAlignment": 69
    },
    "completedAt": "2026-04-02T04:09:00.000Z"
  },
  "trends": {
    "sentiment": 4,
    "alignment": 4,
    "consistency": 2,
    "factualAlignment": 2
  },
  "averages": {
    "sentiment": 75.5,
    "alignment": 62.0,
    "consistency": 80.3,
    "factualAlignment": 69.8
  },
  "history": [
    {
      "snapshotId": "snap_2026_04",
      "month": 4,
      "year": 2026,
      "label": "04/2026",
      "scores": {
        "sentiment": 74,
        "alignment": 61,
        "consistency": 80,
        "factualAlignment": 69
      },
      "completedAt": "2026-04-02T04:09:00.000Z"
    },
    {
      "snapshotId": "snap_2026_05",
      "month": 5,
      "year": 2026,
      "label": "05/2026",
      "scores": {
        "sentiment": 78,
        "alignment": 65,
        "consistency": 82,
        "factualAlignment": 71
      },
      "completedAt": "2026-05-03T04:12:00.000Z"
    }
  ],
  "meta": {
    "months": 6,
    "dataPoints": 2
  },
  "nextAnalysisDate": "2026-06-01T00:00:00.000Z"
}
```

## Erreurs

| Statut | Code | Description |
| - | - | - |
| `400` | `INVALID_PARAMETER` | Valeur de `months` invalide |
| `401` | erreur de passerelle | Échec de l’authentification |
| `404` | `BRAND_NOT_FOUND` | Marque introuvable ou inaccessible |
| `429` | erreur de passerelle | Limite de débit dépassée ; respectez `Retry-After` |


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