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

# Asynchrone Tasks

> Lebenszyklus, Status, Priorität und Aufbewahrung von Tasks.

Es gibt keinen synchronen Endpunkt. Eine KI-Engine abzufragen dauert Sekunden bis Minuten, daher wird jede Anfrage zu
einem dauerhaft gespeicherten Task in der Warteschlange, den Sie später abholen.

## Lebenszyklus

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

## Status

<ResponseField name="QUEUED" type="status">
  Angenommen und dauerhaft gespeichert. Wartet auf einen Worker.
</ResponseField>

<ResponseField name="PROCESSING" type="status">
  Ein Worker hält eine Lease auf den Task und steuert die Engine.
</ResponseField>

<ResponseField name="COMPLETED" type="status">
  Endzustand. Das Feld `response` ist befüllt.
</ResponseField>

<ResponseField name="FAILED" type="status">
  Endzustand. Das Feld `error` enthält den Grund.
</ResponseField>

Ein Task mit vorübergehendem Fehler (Engine-Timeout, temporärer Fehler) kehrt zu `QUEUED` zurück und wird erneut
versucht. Erst wenn alle Versuche aufgebraucht sind, landet er in `FAILED`. Übergänge `PROCESSING → QUEUED` sind also
normal und kein Anlass für einen Alarm.

## Priorität

`priority` bleibt aus Kompatibilitätsgründen erhalten und wird in den Task-Metadaten zurückgegeben. Erlaubt sind `1`
bis `10`, Standard ist `1`, und Werte außerhalb des Bereichs werden in den Bereich gezogen statt abgelehnt.

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

Die Ausführungsreihenfolge ist weder durch Priorität noch durch Einreichzeit oder Konto garantiert. Bei abhängiger
Arbeit warten Sie, bis der vorherige Task abgeschlossen ist, bevor Sie den nächsten einreichen. Die
Parallelitätsgrenzen des Tarifs gelten für wartende und laufende Tasks.

## Aufbewahrung

Abgeschlossene Tasks sind **24 Stunden nach Abschluss** über öffentliches Polling verfügbar. Danach liefert
`GET /v1/async/task/{id}` `404 NOT_FOUND`, dieselbe Antwort wie für eine id, die nie existiert hat. Der zugrunde liegende
Datensatz wird dauerhaft aufbewahrt; der Ablauf begrenzt öffentliches Polling und manuelles erneutes Senden von
Webhooks, nicht die Speicherung. Automatische Webhook-Wiederholungen laufen davon unabhängig weiter.

Wenn Sie auf Polling statt auf Webhooks setzen, holen Sie die Ergebnisse deutlich innerhalb dieses Zeitraums ab.

## Webhook oder Polling

Bevorzugen Sie Webhooks. Polling ist der Weg zur Wiederherstellung.

| | Webhook | Polling |
| - | - | - |
| Latenz bis zum Ergebnis | Sofort bei Abschluss | Ihr Polling-Intervall |
| Last auf der API | Ein POST pro Task | Ein GET pro Abfrage und Task |
| Öffentlicher Endpunkt nötig | Ja | Nein |
| Bei Ausfall Ihres Dienstes | \~30 Min. Wiederholungen, dann verworfen | Ja, für 24 h |

Ein robuster Client macht beides: Er nutzt den Webhook als schnellen Weg und gleicht per Polling alles ab, wovon er
vor Ende des Aufbewahrungsfensters nichts gehört hat.