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

> Obtenez les prompts paginés, avec options de recherche et de filtre.

Liste les prompts suivis avec le nombre de réponses et les indicateurs SELF au niveau des réponses. Un prompt peut avoir une étape du tunnel, un Topic et des Tags.

<Note>
  Consultez [Entités](/fr/developers/entities#prompt) pour la structure complète de l’objet Prompt, et [Topic](/fr/developers/entities#topic) / [Tag](/fr/developers/entities#tag) pour les objets de classement.
</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. Renvoie les prompts ayant reçu au moins une réponse dans la fenêtre. Sans valeur, toutes les données sont renvoyées.
</ParamField>

<ParamField query="startDate" type="string">
  Date de début au format `YYYY-MM-DD` (par exemple `2026-03-05`). 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` (par exemple `2026-03-31`). Fournissez-la avec `startDate` ; une borne seule est actuellement ignorée. Ne combinez pas la paire de dates complète avec `period`.
</ParamField>

<Note>
  Avec une plage de dates, la liste des prompts et les agrégats `include=details` par prompt (`answersCount`, `competitors[].mentions`, `brandMentionCount`, `sources[].citations`) sont limités à cette fenêtre. Les prompts exécutés plusieurs fois apparaissent dès qu’au moins une de leurs exécutions tombe dans la plage.
</Note>

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

<ParamField query="personaIds" type="string">
  UUID de Personas actuellement rattachées au prompt, séparés par des virgules. Utilisez `default` pour les prompts sans Persona, ou `all` pour ne pas filtrer.
</ParamField>

<ParamField query="countries" type="string">
  Codes ISO 3166-1 alpha-2 séparés par des virgules (par exemple `FR,BE`). Conserve les prompts dont les pays configurés effectifs incluent l’un d’eux ; ce n’est pas le pays des réponses passées. 50 codes au maximum ; un code invalide renvoie `400`.
</ParamField>

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

<ParamField query="offset" type="number" default="0">
  Décalage de pagination
</ParamField>

<ParamField query="sort" type="string" default="lastGeneratedAt">
  Champ de tri : `lastGeneratedAt`, `answersCount`, `text`, `createdAt`
</ParamField>

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

<ParamField query="include" type="string">
  Indiquez `details` pour enrichir chaque prompt avec les agrégats de concurrents, de sources, de mentions de la marque et de stabilité des sources. Sans ce paramètre, la réponse ne contient que les champs de base listés ci-dessous.
</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 prompts correspondant aux filtres</ResponseField>
    <ResponseField name="count" type="number">Nombre de prompts 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="prompts" type="array">
  <Expandable title="Objet Prompt">
    <ResponseField name="id" type="string">Identifiant du prompt</ResponseField>
    <ResponseField name="text" type="string">Texte du prompt</ResponseField>
    <ResponseField name="topic" type="string">Nom du Topic associé</ResponseField>
    <ResponseField name="type" type="string">Type de prompt (TOFU/MOFU/BOFU/POST\_PURCHASE)</ResponseField>
    <ResponseField name="tags" type="array">Liste des noms de Tags</ResponseField>
    <ResponseField name="personas" type="array">Personas actuellement rattachées au prompt (`id`, `name`, `description`)</ResponseField>
    <ResponseField name="modelIds" type="array">Identifiants des modèles actuellement configurés sur le prompt</ResponseField>
    <ResponseField name="monitoringEnabled" type="boolean">Indique si le suivi planifié est activé</ResponseField>
    <ResponseField name="frequency" type="string | null">Fréquence de suivi effective : `NONE`, `DAILY`, `WEEKLY` ou `MONTHLY`</ResponseField>
    <ResponseField name="frequencyInherited" type="boolean">Indique si la fréquence est héritée de la valeur par défaut de la marque</ResponseField>
    <ResponseField name="boostCount" type="number">Réponses demandées par modèle et par exécution</ResponseField>
    <ResponseField name="answersCount" type="number">Nombre de réponses générées</ResponseField>
    <ResponseField name="mentionRate" type="number">Réponses avec une mention SELF divisées par les réponses avec une mention SELF ou DIRECT</ResponseField>
    <ResponseField name="sourceRate" type="number">Réponses avec une citation SELF divisées par les réponses avec une citation SELF ou DIRECT</ResponseField>
    <ResponseField name="lastGeneratedAt" type="string">Horodatage de la dernière génération (ISO 8601)</ResponseField>
  </Expandable>

  <Expandable title="Champs supplémentaires avec include=details">
    <ResponseField name="competitors" type="array">
      Liste des concurrents mentionnés dans l’ensemble des réponses de ce prompt.
      Chaque objet contient `name` (string), `mentions` (number) et `relationship` (`SELF`, `DIRECT`, `INDIRECT`).
    </ResponseField>

    <ResponseField name="competitorsCount" type="number">Nombre de concurrents distincts mentionnés</ResponseField>
    <ResponseField name="competitorMentionsTotal" type="number">Total des mentions de concurrents dans l’ensemble des réponses</ResponseField>
    <ResponseField name="brandMentioned" type="boolean">Indique si votre marque a été mentionnée dans au moins une réponse</ResponseField>
    <ResponseField name="brandMentionCount" type="number">Nombre de fois où votre marque a été mentionnée</ResponseField>

    <ResponseField name="sources" type="array">
      Liste des domaines sources cités dans l’ensemble des réponses de ce prompt.
      Chaque objet contient `domain` (string), `citations` (number) et `isSelf` (boolean).
    </ResponseField>

    <ResponseField name="sourcesCount" type="number">Nombre de domaines sources distincts cités</ResponseField>
    <ResponseField name="sourceCitationsTotal" type="number">Total des citations de sources dans l’ensemble des réponses</ResponseField>
    <ResponseField name="sourceStability" type="number">Pourcentage des domaines sources distincts présents dans chaque réponse du périmètre lorsqu’il y a plus d’une réponse ; sinon `0`</ResponseField>
    <ResponseField name="createdAt" type="string">Horodatage de création du prompt (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

## Exemple de requête

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

## Exemple de réponse

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 1,
    "limit": 10,
    "offset": 0
  },
  "prompts": [
    {
      "id": "prompt_01",
      "text": "Which analytics platforms support warehouse exports?",
      "topic": "Data exports",
      "type": "TOFU",
      "tags": ["reviews", "comparison"],
      "answersCount": 2,
      "mentionRate": 50.0,
      "sourceRate": 25.0,
      "lastGeneratedAt": "2026-07-19T10:00:00.000Z"
    }
  ]
}
```

## Exemple de réponse avec `include=details`

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

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 1,
    "limit": 10,
    "offset": 0
  },
  "prompts": [
    {
      "id": "prompt_01",
      "text": "Which analytics platforms support warehouse exports?",
      "topic": "Data exports",
      "type": "TOFU",
      "tags": ["reviews", "comparison"],
      "answersCount": 2,
      "mentionRate": 50.0,
      "sourceRate": 25.0,
      "lastGeneratedAt": "2024-12-19T10:00:00.000Z",
      "competitors": [
        { "name": "Acme Analytics", "mentions": 3, "relationship": "SELF" },
        { "name": "Rival Labs", "mentions": 8, "relationship": "DIRECT" },
        { "name": "Northstar Data", "mentions": 5, "relationship": "DIRECT" }
      ],
      "competitorsCount": 3,
      "competitorMentionsTotal": 16,
      "brandMentioned": true,
      "brandMentionCount": 3,
      "sources": [
        { "domain": "acme.example", "citations": 2, "isSelf": true },
        { "domain": "reviews.example", "citations": 4, "isSelf": false },
        { "domain": "publisher.example", "citations": 3, "isSelf": false }
      ],
      "sourcesCount": 3,
      "sourceCitationsTotal": 9,
      "sourceStability": 33.33,
      "createdAt": "2026-07-01T10:00:00.000Z"
    }
  ]
}
```

## Erreurs

| Statut | Signification |
| - | - |
| `400` | Paramètre de requête 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.