Asynchronous operations

Some operations call external providers (a transcriber, an LLM, the YouTube API) and can take seconds to minutes. Instead of blocking, these endpoints accept the work and return immediately with HTTP 202 and an execution you track to completion.

Which endpoints are async

Endpoint	Returns
`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 }`

Everything else (reads, CRUD on collections/reporters/workflows/schedules) is synchronous — it returns the final result directly.

The execution lifecycle

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

The 202 body gives you an execution with an execution_id and an initial status:

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

Tracking to completion (polling)

Poll the execution until it leaves 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)

The detail response includes the execution, the workflow that ran, per-step summaries (LLM input/output), and step_inputs for steps not yet run.

To see everything currently in flight, call GET /v1/executions/me?active=1 — it returns only pending/running executions. Handy for a dashboard or a “still working” indicator.

Realtime (app only)

The web app doesn’t poll — it subscribes to the realtime WebSocket (wss://api.clipping.cc/v1/realtime?token=<jwt>) and receives event messages as executions progress.

The WebSocket authenticates with a session JWT only (in the token query param) — an API key cannot open it. If you’re integrating with an API key, poll GET /v1/executions/{id} as shown above.

Cost

The 202 itself draws the route’s flat fee (e.g. 0.01 coin for running a transcript). The real provider cost is drawn as pass-through from the resource owner while the job runs — so a job can still end in 402 if the owner runs out of balance mid-flight.

Get started

Core concepts

Guides

Asynchronous operations

Which endpoints are async

The execution lifecycle

Tracking to completion (polling)

Realtime (app only)

Cost

​Which endpoints are async

​The execution lifecycle

​Tracking to completion (polling)

​Realtime (app only)

​Cost

Which endpoints are async

The execution lifecycle

Tracking to completion (polling)

Realtime (app only)

Cost