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(
    body: StartRunBody | Mapping[str, Any] | None = None,
    /,
    *,
    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(run_id: str, /, *, timeout: float | None = None) -> Run

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

client.runs.cancel()

cancel(
    run_id: str,
    /,
    *,
    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(
    run_id: str,
    body: ResumeRunBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> None

Resume a suspended run at a waitpoint (not available in this release). POST /v1/runs/{runId}/resume

Not available in this release: always 422 run-resume-not-supported, and no waitpoint is completed. Every waitpoint a run can wait at belongs to an approval or to the runtime itself. A run waiting for an approval continues when a reviewer decides it: POST /v1/approvals/{approvalId}/complete.

client.runs.journal()

journal(
    run_id: str,
    /,
    *,
    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(
    run_id: str,
    /,
    *,
    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(run_id: str, /, *, 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(
    run_id: str,
    /,
    *,
    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.