client.runs

client.runs — the runs operations.

On AsyncKindgi every method is the same, awaited.

client.runs.list()

list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    parent_run_id: str | None = None,
    top_level: bool | None = None,
    include: Literal['output'] | None = None,
    timeout: float | None = None,
) -> RunCollectionPage

List runs. GET /v1/runs

Cursor-paginated. Fixed sort order: createdAt desc, id desc.

client.runs.start()

start(
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> Run

Start a run. POST /v1/runs

One primitive, discriminated subject (agent XOR flow). When the deployment issues public run tokens, the response carries publicAccessToken: a read-only token for this run (15 minutes by default) to hand to a browser, which follows the run with it on GET /v1/runs/{runId}/progress and its stream.

client.runs.get()

get(*, timeout: float | None = None) -> Run

Fetch a run. GET /v1/runs/{runId}

client.runs.cancel()

cancel(*, idempotency_key: str | None = None, timeout: float | None = None) -> Run

Cancel a run. POST /v1/runs/{runId}/cancel

Cancelling a run that already reached a terminal state returns 409 run-already-terminal.

client.runs.resume()

resume(
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> Run

Resume a suspended run at a waitpoint. POST /v1/runs/{runId}/resume

Completes a pending waitpoint token (RunBinding.completeToken), then resumes the run in the same request; the response shows the status it reached. Resuming without a waitpointId returns 400 bad-input.

client.runs.journal()

journal(*, since: int | None = None, timeout: float | None = None) -> RunJournalPage

Read the durable journal for a run. GET /v1/runs/{runId}/journal

Returns raw JournalEntry values from the run journal (@kindgi/runtime). Distinct from the SSE wire enum — see docs/API-ROUTE-CONVENTIONS.md §6.

client.runs.stream()

stream(
    *,
    last_event_id: str | None = None,
    timeout: float | None = None,
) -> Iterator[RunEvent]

Server-Sent Events stream of RunEvent frames. GET /v1/runs/{runId}/stream

Each SSE frame is one RunEvent per @kindgi/specs/run-event.schema.json. Reconnect via Last-Event-Id: <runId>:<sequence>. The server ends the stream after the run's terminal event, or after 5 minutes: reconnect with Last-Event-Id to continue.

client.runs.progress()

progress(*, timeout: float | None = None) -> RunProgress

A run's progress (status and timing, no data). GET /v1/runs/{runId}/progress

The run's status and timing, without its input, output or failure message: safe to show in a browser. Accepts an API token, or a public run token (kgi_pt_…) that names the run or one of its ancestors.

client.runs.progress_stream()

progress_stream(
    *,
    last_event_id: str | None = None,
    timeout: float | None = None,
) -> Iterator[RunProgressEvent]

Server-Sent Events stream of a run's progress. GET /v1/runs/{runId}/progress/stream

Each SSE frame is one RunProgressEvent: what happened, on which node, when — no payloads. Accepts an API token, or a public run token that names the run or one of its ancestors. Reconnect via Last-Event-Id; the server ends the stream after the run's terminal event, or after 5 minutes.