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

> Listez la file de recommandations priorisées du Centre d’actions.

Renvoie la file actuelle du Centre d’actions d’une marque. Les scores, paliers et indicateurs de gain rapide sont des résultats déterministes des règles de notation actuelles du Centre d’actions ; considérez-les comme des aides à la priorisation, pas comme des résultats prédits.

<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="status" type="string">
  Filtre par statut : `SUGGESTED` (en attente de tri), `PENDING`, `IN_PROGRESS`,
  `COMPLETED`, `DISMISSED`, `RESOLVED` (signal disparu, fermeture automatique).
  Par défaut, la file active : `SUGGESTED` + `PENDING` + `IN_PROGRESS`.
</ParamField>

<ParamField query="type" type="string">
  Filtre par type d’action : `CONTENT_GAP`, `CONTENT_OPTIMIZE`, `TECHNICAL_FIX`,
  `SCHEMA_ADD`, `AUTHORITY_BUILD`, `SOURCE_OUTREACH`, `COMPETITOR_ANALYSIS`,
  `PERCEPTION_FIX`, `SEARCH_TARGET`, `SOCIAL_ENGAGE`, `PRODUCT_OPTIMIZE`,
  `LOCAL_OPTIMIZE`
</ParamField>

<ParamField query="category" type="string">
  Filtre par catégorie : `TECHNICAL`, `CONTENT`, `AEO`, `AUTHORITY`, `VISIBILITY`
</ParamField>

<ParamField query="providers" type="string">
  Filtre selon les fournisseurs à l’origine des données observées. Accepte des identifiants de fournisseurs répétés ou séparés par des virgules.
</ParamField>

<ParamField query="topicIds" type="string">
  Filtre par identifiants de Topics. Accepte des UUID répétés ou séparés par des virgules.
</ParamField>

<ParamField query="tagIds" type="string">
  Filtre par identifiants de Tags. Accepte des UUID répétés ou séparés par des virgules.
</ParamField>

<ParamField query="tagOperator" type="string" default="or">
  Combine les Tags sélectionnés par `or` ou `and`.
</ParamField>

<ParamField query="funnelStages" type="string">
  Filtre par `TOFU`, `MOFU`, `BOFU` ou `POST_PURCHASE`. Accepte des valeurs répétées ou séparées par des virgules.
</ParamField>

<ParamField query="period" type="string" default="all">
  Période des données : `1`, `7`, `14`, `30`, `90`, `all` ou `custom`.
</ParamField>

<ParamField query="periodStart" type="string">
  Date de début au format `YYYY-MM-DD`. Obligatoire avec `periodEnd` lorsque `period=custom`.
</ParamField>

<ParamField query="periodEnd" type="string">
  Date de fin au format `YYYY-MM-DD`. Obligatoire avec `periodStart` lorsque `period=custom`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Nombre maximal d’actions renvoyées (maximum : 100)
</ParamField>

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

## Réponse

<ResponseField name="data" type="array">
  Actions triées par priorité (la plus haute d’abord), puis par date de création.

  <Expandable title="Objet action">
    <ResponseField name="id" type="string">
      Identifiant unique de l’action
    </ResponseField>

    <ResponseField name="type" type="string">
      Type d’action (voir le filtre `type` pour les valeurs)
    </ResponseField>

    <ResponseField name="category" type="string">
      Catégorie de l’action
    </ResponseField>

    <ResponseField name="sourceType" type="string">
      Famille de détecteur à l’origine de l’action (par exemple `PAGE_ISSUE`,
      `QUESTION_GAP`, `SOURCE_OPPORTUNITY`, `SEARCH_QUERY`)
    </ResponseField>

    <ResponseField name="scope" type="string">
      Nature du travail : `ON_SITE`, `OFF_SITE` ou `SETUP`
    </ResponseField>

    <ResponseField name="title" type="string">
      Titre de l’action
    </ResponseField>

    <ResponseField name="description" type="string">
      Quoi faire et pourquoi
    </ResponseField>

    <ResponseField name="sourceUrl" type="string | null">
      URL externe à l’appui de l’action, le cas échéant
    </ResponseField>

    <ResponseField name="targetProvider" type="string | null">
      Fournisseur IA ciblé par cette action (null = niveau de la marque)
    </ResponseField>

    <ResponseField name="evidenceProviders" type="array">
      Identifiants des fournisseurs explicitement présents dans les données sous-jacentes
    </ResponseField>

    <ResponseField name="evidenceScope" type="string">
      `OBSERVED`, `CURRENT` ou `UNATTRIBUTED`
    </ResponseField>

    <ResponseField name="forceTier" type="string">
      Palier de priorité : `CRITICAL`, `HIGH` ou `STANDARD`
    </ResponseField>

    <ResponseField name="priorityScore" type="number">
      Score de 0 à 100 ancré sur le palier : Critical de 70 à 100, High de 40 à 69 et Standard de 10 à 39. Il est calculé à partir du palier, du badge de demande, de l’effort et du périmètre de fournisseurs.
    </ResponseField>

    <ResponseField name="demandBadge" type="number">
      Signal de demande de 1 à 5
    </ResponseField>

    <ResponseField name="isQuickWin" type="boolean">
      Indique si l’heuristique du Centre d’actions classe l’élément comme gain rapide
    </ResponseField>

    <ResponseField name="effort" type="string">
      Charge estimée : `LOW`, `MEDIUM` ou `HIGH`
    </ResponseField>

    <ResponseField name="status" type="string">
      Statut dans le cycle de vie
    </ResponseField>

    <ResponseField name="signals" type="object | null">
      Signaux chiffrés bruts à l’origine de la priorité (citations, occurrences
      de Query Fan-Out, impressions, pression concurrentielle, pages concernées…)
    </ResponseField>

    <ResponseField name="impactJustification" type="string | null">
      Explication enregistrée des signaux utilisés pour la priorisation
    </ResponseField>

    <ResponseField name="effortJustification" type="string | null">
      Explication de l’effort estimé
    </ResponseField>

    <ResponseField name="baselineMetric" type="number | null">
      Valeur de l’indicateur enregistrée à la création de l’action
    </ResponseField>

    <ResponseField name="targetMetric" type="number | null">
      Valeur cible de l’indicateur, le cas échéant
    </ResponseField>

    <ResponseField name="questionId" type="string | null">
      Prompt suivi lié, le cas échéant
    </ResponseField>

    <ResponseField name="checklist" type="array">
      Checklist générée associée à l’action
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Date de création ISO 8601
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Date de dernière mise à jour ISO 8601
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  `total`, `limit`, `offset`, `hasMore`
</ResponseField>

## Exemple de requête

<RequestExample>
  ```bash cURL theme={null}
  curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/actions?status=SUGGESTED&limit=10" \
    -H "Authorization: Bearer $QWAIRY_API_TOKEN"
  ```
</RequestExample>

## Exemple de réponse

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "action_01",
        "type": "SOURCE_OUTREACH",
        "category": "AUTHORITY",
        "sourceType": "SOURCE_OPPORTUNITY",
        "scope": "OFF_SITE",
        "title": "Review citation gap for Publisher Example",
        "description": "Stored answers cite this source 16 times without a SELF mention.",
        "sourceUrl": "https://publisher.example",
        "targetProvider": null,
        "evidenceProviders": ["example-provider"],
        "evidenceScope": "OBSERVED",
        "forceTier": "HIGH",
        "priorityScore": 53,
        "demandBadge": 3,
        "isQuickWin": false,
        "effort": "MEDIUM",
        "status": "SUGGESTED",
        "signals": {
          "citations": 16,
          "sourceCategory": "MEDIA",
          "competitivePressure": 2
        },
        "impactJustification": "Source cited 16x by AI answers without mentioning the brand.",
        "effortJustification": "Outreach: research the contact, pitch, and follow up.",
        "baselineMetric": null,
        "targetMetric": null,
        "questionId": null,
        "checklist": [
          "Review what content the source already cites",
          "Compare the cited pages with your existing evidence",
          "Decide whether an outreach hypothesis is worth testing",
          "Record the test and monitor later observations"
        ],
        "createdAt": "2026-06-12T05:00:00.000Z",
        "updatedAt": "2026-06-12T05:00:00.000Z"
      }
    ],
    "pagination": { "total": 42, "limit": 10, "offset": 0, "hasMore": true }
  }
  ```
</ResponseExample>

## Erreurs

| Statut | Signification |
| - | - |
| `400` | Filtre d’énumération, de taxonomie, de fournisseur ou de période 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.