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

# Tareas asíncronas

> Ciclo de vida de la tarea, estados, prioridad y retención.

No hay endpoint síncrono. Consultar un motor de IA tarda de segundos a minutos, así que cada solicitud se
convierte en una tarea en cola, persistente, que recoges después.

## Ciclo de vida

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

## Estados

<ResponseField name="QUEUED" type="status">
  Aceptada y persistida. Esperando a un worker.
</ResponseField>

<ResponseField name="PROCESSING" type="status">
  Un worker tiene un lease sobre la tarea y está operando el motor.
</ResponseField>

<ResponseField name="COMPLETED" type="status">
  Estado final. El campo `response` está rellenado.
</ResponseField>

<ResponseField name="FAILED" type="status">
  Estado final. El campo `error` indica el motivo.
</ResponseField>

Una tarea que sufre un fallo transitorio (timeout del motor, error transitorio) vuelve a `QUEUED` y se reintenta.
Solo cuando se agotan los reintentos queda en `FAILED`, así que las transiciones `PROCESSING → QUEUED` son normales
y no deben disparar alertas.

## Prioridad

`priority` se conserva por compatibilidad y se devuelve en los metadatos de la tarea. Acepta de `1` a `10`, por
defecto `1`, y los valores fuera de rango se ajustan al rango en lugar de rechazarse.

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

El orden de ejecución no está garantizado por prioridad, hora de envío ni cuenta. Para trabajo dependiente, espera
a que la tarea anterior termine antes de enviar la siguiente. Los límites de concurrencia del plan se aplican a las
tareas en cola y en proceso.

## Retención

Las tareas finalizadas están disponibles por sondeo público durante **24 horas tras completarse**. Después,
`GET /v1/async/task/{id}` devuelve `404 NOT_FOUND`, la misma respuesta que un id que nunca existió. El registro
subyacente se conserva de forma permanente; la caducidad limita el sondeo público y la reproducción manual de
webhooks, no el almacenamiento. Los reintentos automáticos de webhook continúan de forma independiente.

Si dependes del sondeo en lugar de webhooks, recoge los resultados con margen dentro de ese plazo.

## Webhook o sondeo

Prefiere los webhooks. El sondeo es la vía de recuperación.

| | Webhook | Sondeo |
| - | - | - |
| Latencia hasta el resultado | Inmediata al completarse | Tu intervalo de sondeo |
| Carga sobre la API | Un POST por tarea | Un GET por sondeo y tarea |
| Requiere endpoint público | Sí | No |
| Si tu servicio se cae | Reintentos \~30 min, luego se descarta | Sí, durante 24 h |

Un cliente robusto usa ambos: toma el webhook como vía rápida y concilia por sondeo lo que no te haya llegado antes
de que se cierre la ventana de retención.