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

# Runs

> Submit pipeline routes, inspect progress, stream events, and control execution

A run is one execution of one source-to-sink route from an immutable pipeline
version. Its messages are defined in `protos/ingestion/v1/runs.proto`.

## RPCs

| RPC | Description |
| - | - |
| `RunPipeline` | Compile the current version and submit one run per route |
| `ListRuns` | List runs with status and time-window filters |
| `GetRun` | Read one run and its per-resource progress |
| `TailRun` | Stream current and live run events |
| `SignalRun` | Pause or resume a run; cancel bounded work or stop continuous execution |

## RunPipeline

One call may produce several runs. A graph that fans one source out to two sinks
has two routes, so the response contains two `edge_runs`, each keyed by its
`pipeline_edge_key`.

`client_token` distinguishes retry from intent. Reuse the token when retrying the
same user action; choose a new token for a deliberate rerun. The token contributes
to stable run IDs, preventing a transport retry from dispatching duplicates.

`worker_configuration` overrides pipeline worker settings field by field. The
resolved configuration is copied into each run so later pipeline edits cannot
change work already requested.

A zero value asks the engine or sink to choose its normal default:

| Field | Current behavior |
| - | - |
| `batch_max_rows` | Maximum rows in an Arrow batch |
| `batch_max_bytes` | Approximate byte limit used while building an Arrow batch |
| `snapshot_parallelism` | Writer-pool size and source snapshot planning hint; forced to one for ordered/checkpointed routes |
| `checkpoint_every` | Written batches between eligible checkpoint saves; default 25 |
| `fetch_size` | Stored for the run; not currently consumed by the engine |
| `rate_limit` | Stored for the run; not currently consumed by the engine |

## Status and recovery

| Status | Meaning |
| - | - |
| `SCHEDULED` | Created for a future schedule fire |
| `REQUESTED` | Waiting for dispatch |
| `RUNNING` | Owned by a worker |
| `PARTIAL` | Failed with route-wide resumable progress |
| `PAUSED` | Stopped intentionally and eligible for resume |
| `COMPLETED` | Committed successfully |
| `FAILED` | Failed without a safe same-run continuation |
| `CANCELED` | Intentionally aborted |

`PARTIAL` does not mean that any checkpoint happened to exist. Every resource in
the route must meet the safe-resume rules. See
[Runs and recovery](/pages/guides/concepts/runs-and-recovery) for those boundaries.

Continuous runs also expose `execution_mode` and `execution_status`. The latter
separates the requested state from what the worker is doing: an execution can
be draining toward a pause, retrying, or blocked even while the logical run
remains active. Its record and byte totals reflect certified epochs, and
`last_committed_at` records the latest saved commit. See
[Streaming](/pages/guides/concepts/streaming) for how to interpret these states.

## ListRuns

Filter by `pipeline_id`, optional `pipeline_version_id`, repeated `status`, and
a `since_ms`/`until_ms` window over `started_at` (inclusive/exclusive epoch
milliseconds). Windowed queries omit runs that have not started. Search and
sorting fields follow the common API conventions, and list pagination is
described in [Service overview](/pages/api-reference/service/introduction#pagination).

Scheduled pipelines normally show future `SCHEDULED` rows. The scheduler
creates the next run in advance and promotes it to requested at fire time.

## GetRun

Returns `RunSnapshot` with run-level status, record and byte totals, errors,
lifecycle timestamps, connection IDs, worker usage, and per-resource progress.

The protobuf also contains `at_seq`, but the current `GetRun` implementation does
not populate it, so clients should treat it as zero/reserved rather than as a
snapshot consistency token.

## TailRun

`TailRun` is the server-streaming RPC. Each `RunEvent` includes its wire event
type, resource, monotonic sequence, and relevant measurements.

With `should_replay`, the server first synthesizes events from stored resource
progress and marks them `is_replay: true`, then forwards live facts. This helps a
reconnecting client render current progress before new events arrive. The stream
closes after a terminal or paused/canceled event. An event bus is required;
without one the RPC returns `failed_precondition`.

## SignalRun

For bounded runs, send `PAUSE`, `RESUME`, or `CANCEL` with a `run_id`. An optional `tenant_id` is
checked against the run when present.

The allowed transition depends on current state:

* requested runs can be paused or canceled without worker coordination;
* running pause/cancel requests wait for the worker to acknowledge its safe
  commit or abort boundary;
* paused and partial runs can be resumed to requested or canceled; and
* repeated signals that already match the intended state are idempotent where
  safe, while invalid transitions return `failed_precondition`.

Running signals require both an event bus and datastore support for atomic run
transitions. A request may also end with `deadline_exceeded` or `canceled` while
waiting for worker acknowledgement.

Continuous runs accept `PAUSE`, `RESUME`, and `STOP`. These update the desired
state and return the current execution status while the worker responds.
An optional `expected_revision` detects a conflicting control change; a stale
revision returns `aborted`. A stopped execution cannot be resumed and requires
a new start.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.