Create Execution

Start a new execution of a workflow definition within a session.

POST /revisions/:id/data/command (Command: create_execution)

Request Body

Parameter	Type	Required	Description
command	string	Yes	Must be create_execution.
target	object	Yes	Where it runs: {"session": "<id or alias>"}, resolved in the route’s revision. target holds only session, a non-blank string of at most 64 characters — the route already names the organization, blob and revision.
workflow	object	Yes	What to run. See The workflow reference.
input_data	array	No	List of input objects {"alias": "foo", "value": {...}}.
description	string	No	At most 256 characters, stored on the execution. A schedule sends its own description here on every fire.

workflow takes one of three shapes at a glance: {definition} for the session’s own revision, {blob, revision, definition} for a blob named by id, in whatever organization it belongs to, or {org, blob, revision, definition} fully qualified — see The workflow reference for the full grammar.

Response

Parameter	Type	Description
execution	object	The created execution object.

execution carries workflow, definition and snapshot, which a create response always sets to "created" — see Get Execution for the full shape.

It also carries session_id — the session’s id, whichever of id or alias target.session named it by.

The snapshot is taken after the access checks and before the record is written; if the copy fails, the request fails and no execution exists. See The execution snapshot.

Limits are fixed at creation. An execution’s limits come from the session’s blob, wherever its definition lives. create_execution resolves workflow.processor_runs_per_execution, workflow.execution_seconds, workflow.code_run_seconds, workflow.code_imports and workflow.session_objects_per_session once, and the execution keeps those values until it ends — see Limits during a run. A schedule’s fire is checked the same way, and a fire that a limit refuses is recorded as refused.

Execution identity. An execution must trace to a user: the request needs an identified caller, or the call returns 403. Interactive callers (JWT or API key) and scheduled invocations (via create_schedule) always carry one; the guard fails closed if that identity is ever missing.

Errors

Status	Error	Cause
400	invalid_request_body	target carries a key other than session, target.session is blank or over 64 characters, the body carries a field this page does not list, or description is over 256 characters — see Migrating from the removed shapes.
400	invalid_workflow_reference	workflow is malformed — wrong shape, or a combination the grammar refuses.
400	invalid_definition_category	workflow.definition is a definition id naming a playground definition the caller can reach. An alias never gets this error — alias lookups see only the workflow category.
403	forbidden	target.session does not resolve to a session in the route’s revision, or any failure to resolve or reach the workflow source — identical whatever the cause.
409	session_not_open	The session exists but is not open.
400	limit_exceeded	limit.id says which: the session already holds as many executions as workflow.executions_per_session allows; the organization of the session’s blob already has as many executions running as workflow.running_executions_per_org allows; or input_data is larger than workflow.execution_input_bytes, 65,536 bytes. See When a limit is reached.

Example

Request

{
  "command": "create_execution",
  "description": "Nightly data processing run",
  "target": {"session": "nightly-runs"},
  "workflow": {"definition": "data-process"},
  "input_data": [
    { "alias": "input_1", "value": { "type": "string" } }
  ]
}

target.session names the session by its alias, nightly-runs; the execution’s session_id is the id that alias resolved to.