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

# Tarefas assíncronas

> Ciclo de vida da tarefa, status, prioridade e retenção.

Não existe endpoint síncrono. Consultar um mecanismo de IA leva de segundos a minutos, então toda requisição vira uma
tarefa persistente na fila, que você coleta depois.

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

## Status

<ResponseField name="QUEUED" type="status">
  Aceita e persistida. Aguardando um worker.
</ResponseField>

<ResponseField name="PROCESSING" type="status">
  Um worker detém um lease sobre a tarefa e está operando o mecanismo.
</ResponseField>

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

<ResponseField name="FAILED" type="status">
  Estado final. O campo `error` traz o motivo.
</ResponseField>

Uma tarefa que sofre uma falha transitória (timeout do mecanismo, erro passageiro) volta para `QUEUED` e é repetida.
Só depois de esgotar as tentativas ela fica em `FAILED`, então transições `PROCESSING → QUEUED` são normais e não
justificam alerta.

## Prioridade

`priority` é mantido por compatibilidade e devolvido nos metadados da tarefa. Aceita de `1` a `10`, com padrão `1`, e
valores fora do intervalo são ajustados para dentro dele em vez de rejeitados.

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

A ordem de execução não é garantida por prioridade, horário de envio ou conta. Para trabalho dependente, espere a
tarefa anterior terminar antes de enviar a próxima. Os limites de concorrência do plano valem para tarefas na fila e
em processamento.

## Retenção

Tarefas finalizadas ficam disponíveis por polling público durante **24 horas após a conclusão**. Depois disso,
`GET /v1/async/task/{id}` retorna `404 NOT_FOUND`, a mesma resposta de um id que nunca existiu. O registro subjacente é
mantido permanentemente; a expiração limita o polling público e o reenvio manual de webhooks, não o armazenamento. As
novas tentativas automáticas de webhook continuam de forma independente.

Se você depende de polling em vez de webhooks, colete os resultados com folga dentro desse prazo.

## Webhook ou polling

Prefira webhooks. O polling é o caminho de recuperação.

| | Webhook | Polling |
| - | - | - |
| Latência até o resultado | Imediata na conclusão | Seu intervalo de polling |
| Carga na API | Um POST por tarefa | Um GET por consulta por tarefa |
| Exige endpoint público | Sim | Não |
| Se seu serviço cair | Novas tentativas por \~30 min, depois descarta | Sim, por 24 h |

Um cliente robusto usa os dois: recebe o webhook como caminho rápido e reconcilia por polling tudo de que não teve
notícia antes de a janela de retenção fechar.