Reference

Runs

A Run is one execution of a Workflow, read from the engine.

Checked 2026-09-28

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, now or after start_delay or at schedule_time. run_id is the caller's key: the same key and intent return the same Run, a changed intent is refused. An end user's session may call it on a Workflow whose callers is USERS when the session holds the Workflow's permission.
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. An end user's session may call it on a Workflow whose callers is USERS when the session holds the Workflow's permission.
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. An end user's session may call it on a Workflow whose callers is USERS when the session holds the Workflow's permission.
POST	wait	Waits up to timeout (at most 60s) for the Run to close, then returns it, closed or not. Its short name is result: the closed Run carries the handler's output or error. An end user's session may call it on a Workflow whose callers is USERS when the session holds the Workflow's permission.
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, now or after start_delay or at schedule_time. run_id is the caller's key: the same key and intent return the same Run, a changed intent is refused. An end user's session may call it on a Workflow whose callers is USERS when the session holds the Workflow's permission.

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. An end user's session may call it on a Workflow whose callers is USERS when the session holds the Workflow's permission.

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. An end user's session may call it on a Workflow whose callers is USERS when the session holds the Workflow's permission.

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. Its short name is result: the closed Run carries the handler's output or error. An end user's session may call it on a Workflow whose callers is USERS when the session holds the Workflow's permission.

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