> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tâches asynchrones

> Cycle de vie des tâches, statuts, priorité et rétention.

Il n'existe pas d'endpoint synchrone. Interroger un moteur d'IA prend de quelques secondes à quelques minutes :
chaque requête devient donc une tâche durable mise en file, que vous récupérez plus tard.

## Cycle de vie

```mermaid theme={null}
stateDiagram-v2
    [*] --> QUEUED: POST /v1/async/task
    QUEUED --> PROCESSING: worker claims
    PROCESSING --> COMPLETED: engine answered
    PROCESSING --> FAILED: retries exhausted
    PROCESSING --> QUEUED: transient error, requeued
    COMPLETED --> [*]: polling expires after 24h
    FAILED --> [*]: polling expires after 24h
```

## Statuts

<ResponseField name="QUEUED" type="status">
  Acceptée et persistée. En attente d'un worker.
</ResponseField>

<ResponseField name="PROCESSING" type="status">
  Un worker détient un bail sur la tâche et pilote le moteur.
</ResponseField>

<ResponseField name="COMPLETED" type="status">
  État final. Le champ `response` est renseigné.
</ResponseField>

<ResponseField name="FAILED" type="status">
  État final. Le champ `error` indique la raison.
</ResponseField>

Une tâche qui subit un échec transitoire (timeout du moteur, erreur passagère) repasse en `QUEUED` et est relancée.
Ce n'est qu'une fois les tentatives épuisées qu'elle se fige en `FAILED` : les transitions `PROCESSING → QUEUED` sont
donc normales et ne justifient pas d'alerte.

## Priorité

`priority` est conservé pour compatibilité et renvoyé dans les métadonnées de la tâche. Il accepte les valeurs de `1` à
`10`, vaut `1` par défaut, et les valeurs hors plage sont ramenées dans la plage au lieu d'être rejetées.

```json theme={null}
{ "taskType": "GEMINI", "priority": 8, "payload": { "prompt": "..." } }
```

L'ordre d'exécution n'est garanti ni par la priorité, ni par l'heure de soumission, ni par le compte. Pour un travail
dépendant, attendez que la tâche précédente soit terminée avant de soumettre la suivante. Les limites de concurrence
de l'offre s'appliquent aux tâches en file et en cours.

## Rétention

Les tâches terminées sont disponibles via le polling public pendant **24 heures après leur fin**. Ensuite,
`GET /v1/async/task/{id}` renvoie `404 NOT_FOUND`, la même réponse que pour un id qui n'a jamais existé.
L'enregistrement sous-jacent est conservé de façon permanente ; l'expiration limite le polling public et le rejeu
manuel des webhooks, pas le stockage. Les nouvelles tentatives automatiques de webhook se poursuivent indépendamment.

Si vous comptez sur le polling plutôt que sur les webhooks, récupérez les résultats bien avant la fin de ce délai.

## Webhook ou polling

Préférez les webhooks. Le polling est la voie de rattrapage.

| | Webhook | Polling |
| - | - | - |
| Délai d'obtention | Immédiat à la fin | Votre intervalle de polling |
| Charge sur l'API | Un POST par tâche | Un GET par interrogation et par tâche |
| Endpoint public requis | Oui | Non |
| Si votre service tombe | Nouvelles tentatives \~30 min, puis abandon | Oui, pendant 24 h |

Un client robuste fait les deux : il prend le webhook comme voie rapide et rapproche par polling ce dont il n'a pas eu
de nouvelles avant la fin de la fenêtre de rétention.