Menu
Platform
AI
App store purchases
Database
Flags
Jobs and cron
Localization
Monitoring
Notifications
Payments
Queues
Sandboxes
Webhooks
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
Runs
A Run is one execution of a Workflow, read from the engine.
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 | Gets a run. |
GET | list | Lists runs. |
POST | create | Starts a Run of a Workflow. |
POST | 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 | 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 | 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 | Waits up to timeout (at most 60s) for the Run to close, then returns it, closed or not. |
GET | 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
#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
#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
#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
#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
#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
#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
#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