Cycle de vie d'une tâche batch

Les endpoints batch (/batch/distill, /batch/extract) sont asynchrones. Une tâche traverse une petite machine à états ; comprendre ces états t'aide à choisir entre polling et Webhook, et à gérer les échecs partiels.

Sync vs async

	Sync (`/distill`, `/extract`)	Async (`/batch/distill`, `/batch/extract`)
URLs par requête	1	jusqu'à 100
Réponse	Résultat complet dans le corps HTTP	ID de tâche ; résultats récupérés à part
Latence	Une requête, une attente	Soumettre → poll ou Webhook → fetch
Idéal pour	UX temps réel, outillage d'agent, lookups ad hoc	Tâches planifiées, ingestion RAG, monitoring
Mode d'échec	Une URL en erreur fait échouer l'appel	Une URL en erreur fait échouer sa ligne, la tâche continue
Coût en concurrence	Un slot par appel	Un slot pour tout le batch

En cas de doute : une seule URL → sync ; beaucoup d'URLs ou pas pressé → async.

États de la tâche

Status	Signification
`PENDING`	Tâche acceptée, en file
`PROCESSING`	Au moins une URL est en cours de traitement
`COMPLETED`	Toutes les URLs ont atteint un état terminal (succès ou échec)
`FAILED`	Erreur fatale au niveau de la tâche (rare — d'habitude une URL échoue, pas toute la tâche)
`CANCELLED`	Annulation initiée par l'utilisateur via `DELETE`

L'échec d'une URL ne fait pas échouer la tâche. Chaque élément de results[] porte son propre status : PENDING, PROCESSING, SUCCEEDED ou FAILED. La tâche passe à COMPLETED une fois que chaque ligne a atteint un état terminal.

Polling vs Webhook

Taille de tâche	Recommandé	Pourquoi
< 10 URLs	Poll toutes les 5–10 s	L'overhead Webhook ne vaut pas le câblage
10–100 URLs	Webhook	Le polling brûle ~60 allers-retours sur une tâche de 5 minutes
> 100 URLs (plusieurs batches)	Webhook	Chaque batch déclenche une fois à la fin

Voir Webhooks pour la forme du payload, la vérification de signature (HMAC-SHA256) et le comportement de réessai.

Résultats partiels

GET /batch/distill/{id} fonctionne pendant que la tâche est encore PROCESSING — tu obtiens tout ce qui est terminé jusqu'ici. Utile pour des dashboards qui streament les lignes au fil de leur complétion.

import httpx, time

API = "https://openapi.thunderbit.com/openapi/v1"
H = {"Authorization": "Bearer YOUR_API_KEY"}

job = httpx.post(f"{API}/batch/distill", headers=H,
                 json={"urls": urls}).json()
batch_id = job["data"]["id"]

while True:
    body = httpx.get(f"{API}/batch/distill/{batch_id}", headers=H).json()["data"]
    fresh = [r for r in body["results"] if r["status"] == "SUCCEEDED"]
    yield_to_dashboard(fresh)
    if body["status"] in ("COMPLETED", "FAILED", "CANCELLED"):
        break
    time.sleep(5)

Annulation

DELETE /batch/distill/{id} (ou /batch/extract/{id}) ne fonctionne que sur les tâches PENDING ou PROCESSING. Une fois qu'une tâche atteint un état terminal, elle y reste. Les URLs déjà traitées dans une tâche annulée restent facturables ; les URLs en vol qui n'avaient pas terminé ne le sont pas.