Operações assíncronas

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:

{ "execution": { "execution_id": "exc_…", "status": "pending" } }

Acompanhar até concluir (polling)

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

curl https://api.clipping.cc/v1/executions/exc_123 \
  -H "Authorization: Bearer ck_live_…"

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)

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.

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

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.

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.

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.

Começando

Conceitos

Guias

Operações assíncronas

Quais endpoints são assíncronos

O ciclo de vida da execution

Acompanhar até concluir (polling)

Realtime (só o app)

Custo

​Quais endpoints são assíncronos

​O ciclo de vida da execution

​Acompanhar até concluir (polling)

​Realtime (só o app)

​Custo

Quais endpoints são assíncronos

O ciclo de vida da execution

Acompanhar até concluir (polling)

Realtime (só o app)

Custo