---
# @generated by sylphx-gen 0.1.0 from contracts@e145cc7cf1bc9605f2b27439e5e17ed76a1a2fd7e7021906a013f7565e4a0cd5. Do not edit.
title: "Runs"
description: "The `runs` collection of Sylphx Workflows: A Run is one execution of a Workflow, read from the engine."
type: reference
product: workflows
summary: "A Run is one execution of a Workflow, read from the engine."
updated: 2026-09-28
order: 900
---

A Run is one execution of a Workflow, read from the engine. Create starts it: the same `Idempotency-Key` and input return the same Run, a changed input under the same key is refused. A Run ends `succeeded` only from its handler's recorded result, and `cancelled` only from an authenticated cancel the handler acknowledged or a Run that never started.

**Service** Sylphx Workflows · **Resource type** `workflows.sylphx.com/Run` · **Name pattern** `orgs/{org}/projects/{project}/envs/{env}/workflows/{workflow}/runs/{run}` · **Shape** `record`

## Fields

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | `orgs/{org}/projects/{project}/envs/{env}/workflows/{workflow}/runs/{run}`. |
| `uid` | `string` | `run_<cell><ulid>`; never reused. Output only. |
| `meta` | `ResourceMeta` | Resource metadata. |
| `workflow_generation` | `int64` | The Workflow generation the Run pinned at start. Output only. |
| `input` | `struct` | The Run input, at most 256 KiB of JSON. |
| `start_delay` | `duration` | Delay the first invocation by this much. |
| `state` | `RunState` | The Run's lifecycle state. Output only. One of `running`, `succeeded`, `failed`, `cancelled`, `timed_out`. |
| `schedule_fire` | `ScheduleFireRef` | Set when a Schedule fire started the Run. Output only. |
| `batch_position` | `BatchPosition` | Set on a child of a batch Run. Output only. |
| `start_time` | `timestamp` | When the Run started. Output only. |
| `end_time` | `timestamp` | When the Run closed. Output only. |
| `attempt_count` | `int32` | Attempts made so far, across every step. Output only. |
| `output` | `struct` | The handler's `complete` output, once `succeeded`. Output only. |
| `error` | `RunError` | The failure, once `failed` or `timed_out`. Output only. |
| `schedule_time` | `timestamp` | When the first invocation is due: set it directly, or through `start_delay`; at most 365 days ahead. A Run cancelled before then closes `cancelled` with no invocation. |

## Methods

Every method of the collection, in the registry's order, with the scope it
needs. The full request, response and examples are one link away.

| Method | Call | What it does |
| --- | --- | --- |
| `GET` | [`get`](/docs/api/runs#get) | Gets a run. |
| `GET` | [`list`](/docs/api/runs#list) | Lists runs. |
| `POST` | [`create`](/docs/api/runs#create) | Starts a Run of a Workflow. |
| `POST` | [`start_batch`](/docs/api/runs#start-batch) | Starts a batch: a parent Run that fans out one child Run per item, each with a stable index and count. |
| `POST` | [`signal`](/docs/api/runs#signal) | Sends a named signal to a running Run; a `wait` op for that name resumes with its payload. A signal to a closed Run fails with INVALID_STATE. |
| `POST` | [`cancel`](/docs/api/runs#cancel) | Requests cancellation. Timers and waits stop; a running invocation is not interrupted: the handler receives one final invocation with `cancel: true`, and the Run ends `cancelled` when it answers. |
| `POST` | [`wait`](/docs/api/runs#wait) | Waits up to `timeout` (at most 60s) for the Run to close, then returns it, closed or not. |
| `GET` | [`read_history`](/docs/api/runs#read-history) | Reads a page of the Run's immutable history, projected to Sylphx events. |

## get

Gets a run.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/workflow/runs/run` · scope `workflows:read` · effect `read` · [Request, response and examples](/docs/api/runs/get)

## list

Lists runs.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/workflow/runs` · scope `workflows:read` · effect `read` · paginated · [Request, response and examples](/docs/api/runs/list)

## create

Starts a Run of a Workflow.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/workflow/runs` · scope `workflows:run` · effect `write` · [Request, response and examples](/docs/api/runs/create)

## start_batch

Starts a batch: a parent Run that fans out one child Run per item, each with a stable index and count.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/workflow/runs:startBatch` · scope `workflows:run` · effect `write` · [Request, response and examples](/docs/api/runs/start_batch)

## signal

Sends a named signal to a running Run; a `wait` op for that name resumes with its payload. A signal to a closed Run fails with INVALID_STATE.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/workflow/runs/run:signal` · scope `workflows:run` · effect `write` · [Request, response and examples](/docs/api/runs/signal)

## cancel

Requests cancellation. Timers and waits stop; a running invocation is not interrupted: the handler receives one final invocation with `cancel: true`, and the Run ends `cancelled` when it answers.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/workflow/runs/run:cancel` · scope `workflows:run` · effect `destructive` · [Request, response and examples](/docs/api/runs/cancel)

## wait

Waits up to `timeout` (at most 60s) for the Run to close, then returns it, closed or not.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/workflow/runs/run:wait` · scope `workflows:read` · effect `read` · [Request, response and examples](/docs/api/runs/wait)

## read_history

Reads a page of the Run's immutable history, projected to Sylphx events.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/workflows/workflow/runs/run:readHistory` · scope `workflows:read` · effect `read` · [Request, response and examples](/docs/api/runs/read_history)