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

# listRuns

> Gateway RPC for listing runs.

* Method: `listRuns`
* Scope: `run:read`
* Transports: HTTP RPC, WebSocket RPC
* Request: `{ filter?: { status?, limit?, offset?, workflow?, parentRunId?, includeSystem? } }`
* Response: `RunSummary[]`

Errors are versioned as `v1` and include `InvalidRequest`, `Unauthorized`, `Forbidden`, and `Internal`.

`workflow` filters to runs attributed to that workflow key (gateway-started runs match by registered config key, CLI runs by workflow name). `parentRunId` returns only direct children of that run; use `listRunDescendants` for the full transitive tree. Results order newest first. `offset` skips that many rows after the newest-first sort, so `limit` plus `offset` page the full history server-side. It must be a finite, non-negative safe integer no greater than `Number.MAX_SAFE_INTEGER`; fractional, string, negative, non-finite, and unsafe values are `InvalidRequest`.