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

# Tarefas assíncronas

> Os endpoints `jobs` colocam tarefas de captura de ecrã na fila e permitem consultar o estado e os resultados — ideal para alto volume ou capturas longas.

## Primeiros passos

### URL base

```
https://screenshot.cleariflow.com/v1/jobs
```

## Criar uma tarefa

Coloque na fila uma captura de ecrã assíncrona com o mesmo payload `ScreenshotRequest` usado pelo endpoint síncrono.

### Exemplo de pedido

```bash theme={"system"}
curl -X POST 'https://screenshot.cleariflow.com/v1/jobs' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "api_key": "YOUR_UNIQUE_API_KEY",
      "url": "https://cleariflow.com"
    },
    "priority": 10
  }'
```

Um pedido bem-sucedido devolve um identificador de tarefa:

<ResponseExample>
  ```json theme={"system"}
  {
    "job_id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>

### Parâmetros de criação de tarefa

<ParamField body="request" type="Object" required>
  Um objeto `ScreenshotRequest` com os mesmos campos do endpoint síncrono de captura de ecrã (`url`, `render`, `actions`, `cookies`, etc.).
</ParamField>

<ParamField body="priority" type="Integer">
  Prioridade da tarefa. Valores mais altos são processados primeiro. Predefinição: 0.
</ParamField>

## Obter o estado da tarefa

Consulte uma tarefa por ID para verificar o estado e obter resultados após conclusão.

### URL base

```
https://screenshot.cleariflow.com/v1/jobs/{job_id}
```

### Exemplo de pedido

```bash theme={"system"}
curl 'https://screenshot.cleariflow.com/v1/jobs/550e8400-e29b-41d4-a716-446655440000'
```

Enquanto a tarefa está em execução:

<ResponseExample>
  ```json theme={"system"}
  {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "running"
  }
  ```
</ResponseExample>

Quando a tarefa conclui com sucesso:

<ResponseExample>
  ```json theme={"system"}
  {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "done",
    "result": {
      "ok": true,
      "image_base64": "/9j/4AAQSkZJRg...",
      "content_type": "image/jpeg",
      "meta": {
        "elapsed_ms": 8123
      }
    }
  }
  ```
</ResponseExample>

### Valores de estado da tarefa

| Estado    | Descrição                                     |
| --------- | --------------------------------------------- |
| `queued`  | A tarefa aguarda na fila.                     |
| `running` | A sessão do navegador está ativa.             |
| `done`    | Captura concluída; `result` contém a saída.   |
| `failed`  | Captura falhou; `error` contém uma descrição. |

### Parâmetros de resposta

<ResponseField name="job_id" type="String">
  Identificador único da tarefa assíncrona.
</ResponseField>

<ResponseField name="status" type="String">
  Estado atual da tarefa: `queued`, `running`, `done` ou `failed`.
</ResponseField>

<ResponseField name="result" type="Object">
  O objeto de resultado da captura (mesma estrutura que a resposta do endpoint síncrono). Presente quando `status` é `done`.
</ResponseField>

<ResponseField name="error" type="String">
  Mensagem de erro. Presente quando `status` é `failed`.
</ResponseField>

<ResponseField name="meta" type="Object">
  Metadados adicionais sobre a execução da tarefa.
</ResponseField>