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

# Operações assíncronas

> Como trabalho longo retorna 202 + uma execution, e como acompanhar.

Algumas operações chamam provedores externos (transcriber, LLM, API do YouTube) e
podem levar de segundos a minutos. Em vez de bloquear, esses endpoints **aceitam
o trabalho e retornam na hora** com HTTP `202` e uma **execution** que você
acompanha até concluir.

## Quais endpoints são assíncronos

| Endpoint                                      | Retorna                       |
| --------------------------------------------- | ----------------------------- |
| `POST /v1/items/{id}/transcript`              | `202 { execution }`           |
| `POST /v1/reporters/{id}/process`             | `202 { execution }`           |
| `POST /v1/reporters/{id}/process-collection`  | `202 { execution }`           |
| `POST /v1/reporters/{id}/schedules/{sid}/run` | `202 { status, schedule_id }` |

Todo o resto (leituras, CRUD de collections/reporters/workflows/schedules) é
síncrono — devolve o resultado final direto.

## O ciclo de vida da execution

```
pending ──▶ running ──▶ done
                   └──▶ error
```

O corpo do `202` te dá uma `execution` com `execution_id` e um `status` inicial:

```json theme={null}
{ "execution": { "execution_id": "exc_…", "status": "pending" } }
```

## Acompanhar até concluir (polling)

Faça polling da execution até sair de `pending`/`running`:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.clipping.cc/v1/executions/exc_123 \
    -H "Authorization: Bearer ck_live_…"
  ```

  ```python Python theme={null}
  import time, requests

  H = {"Authorization": "Bearer ck_live_…"}

  def wait(execution_id, every=2.0, timeout=300):
      deadline = time.time() + timeout
      while time.time() < deadline:
          r = requests.get(
              f"https://api.clipping.cc/v1/executions/{execution_id}", headers=H
          ).json()
          status = r["execution"]["status"]
          if status in ("done", "error"):
              return r
          time.sleep(every)
      raise TimeoutError(execution_id)
  ```
</CodeGroup>

O detalhe inclui a `execution`, o `workflow` que rodou, os `summaries` por step
(input/output da LLM) e `step_inputs` dos steps ainda não executados.

<Tip>
  Pra ver tudo que está rodando agora, chame `GET /v1/executions/me?active=1` —
  retorna só executions `pending`/`running`. Útil pra um dashboard ou indicador
  de "ainda processando".
</Tip>

## Realtime (só o app)

O app web não faz polling — ele assina o WebSocket de realtime
(`wss://api.clipping.cc/v1/realtime?token=<jwt>`) e recebe mensagens `event`
conforme as executions avançam.

<Warning>
  O WebSocket autentica **só com JWT de sessão** (no query param `token`) — uma
  API key não abre. Se você integra com API key, faça **polling** de
  `GET /v1/executions/{id}` como acima.
</Warning>

## Custo

O próprio `202` debita a taxa flat da rota (ex.: `0,01 coin` pra rodar um
transcript). O **custo real do provedor** é debitado por pass-through do dono do
recurso enquanto o job roda — então um job ainda pode terminar em `402` se o dono
ficar sem saldo no meio.