Skip to main content

Tasks

Units of work moving through a workflow — each transition guarded, dispatched and recorded.

Overview​

A task is one item of work: it names the workflow it runs on, the state it is currently in, and a caller-owned payload. Moving it is not an update — you fire a transition by name and the runtime decides whether that move is legal from the current state, evaluating the workflow's guard and parking the move if it requires approval.

Entering a state can dispatch automation (the workflow's on_enter), so a task is also the thing that drives agents, tools and orchestrations without a caller in the loop. Every move is appended to an immutable history, including the ones a machine made.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Tasks.

Data Model​

Task​

FieldTypeDescription
idstring
project_idstring
workflow_idstring
workflow_versioninteger, nullableThe workflow version this task runs on, fixed when the task was created. Transitions, approval gates and payload validation all resolve through it, so editing the workflow never re-shapes a task already in flight. null for tasks created before pinning existed, which run on the live definition.
titlestring
statestring
statusopen | closed
payloadobjectCaller-owned task data; input to guards (as task.payload) and dispatch mappings. The engine never writes into it except the workflow's declared payload_writes.
metadataobjectThe caller-owned key/value metadata supplied when the task was created, returned verbatim. Absent when the task was created without any. Unlike payload it is invisible to guards and to payload_writes, so it is the place for an attribution label rather than task data.
last_resultanyServer-owned. The result of the current state's last completed dispatch, overwritten on every dispatch. Read-only — exposed to transition guards and on_complete/payload_writes expressions as task.last_result, a namespace a caller cannot write. An agent dispatch's result is the generation's output plus ai_provider_id, the provider that served its model (null when the route that ran named no serving target).
assigneestring, nullable
priorityvery_high | high | medium | low | very_low, nullableA person's assertion of how much the task matters, never derived. null until someone sets it. Set and cleared only with set-task-priority; readable by guards as task.priority.
active_dispatchobject, nullable{ kind, id, status } of the current state's dispatch, if any. kind is generation, orchestration_run or tool_call; a tool_call always carries a null id, since a direct tool call leaves no addressable record. Carries an additional attempt (1-based) while the state's on_enter.retry policy is in effect.
automation_statusrunning | completed | failed | unrouted | paused, nullableStatus of the current state's dispatch. null until a state with an automation is entered. paused means an operator pause suppressed this state's on_enter before it ran, so resume-task will start it.
pause_requested_atstring (date-time), nullableWhen an operator paused this task's automation, or null when no pause is in force.
pause_reasonstring, nullableThe reason supplied with the pause, when one was.
automation_chain_depthintegerServer-owned. How many machine-driven transitions have run back-to-back with no outside intervention — a dispatch outcome routed through on_complete/on_failure, or a transition-task call made by a dispatched run or agent under its stored authority. Any move by a person, a plain API key, or an approval resolution resets it to 0. Once it would exceed the server's limit (TASK_AUTOMATION_CHAIN_LIMIT, default 50) the next such transition is refused with TASK_AUTOMATION_CHAIN_LIMIT, bounding a cycle composed across workflows and orchestrations.
pending_transitionstring, nullableThe name of a requires_approval transition parked awaiting a human decision. Non-null while an ApprovalItem gates the move; the task stays in its current state and no other transition may fire until the approval resolves.
readinessobjectComputed on every read. Only an open dependency blocks; any close, cancelled included, frees what the task held. Guards read it as task.readiness.
entered_state_atstring (date-time)
created_atstring (date-time)
updated_atstring (date-time)

state is the current state's name; reaching a terminal state closes the task.

TaskTransition (history entry)​

FieldTypeDescription
idstring
task_idstring
from_statestring, nullable
to_statestring
transitionstring, nullable
principal_typestringWho made the move: user or api_key for an authenticated caller, automation for the engine acting on an on_enter dispatch outcome, approval for an approval resolution. Named principal_*, not actor_*: these ids never reference the Actors module.
principal_idstring, nullablePublic id of the principal that made the move — the user (user_...), or for api_key auth the key's own id (key_...), distinguishing which key acted. Null for automation, which has no principal: the cause is carried by generation_id / orchestration_run_id / tool_id, one per dispatch kind — exactly one of which is set on an automation move.
generation_idstring, nullableSet when an agent dispatch's generation caused the move.
orchestration_run_idstring, nullableSet when an orchestration dispatch's run caused the move.
tool_idstring, nullableSet when a tool dispatch caused the move. A tool call produces no addressable record of its own, so the tool it called is what records why the task moved.
notestring, nullable
from_workflow_versioninteger, nullableSet on a migration row only: the version the task left, or null for a task that had no pinned version.
to_workflow_versioninteger, nullableSet on a migration row only, the version the task moved onto.
created_atstring (date-time)

transition is the transition's name.

Key Concepts​

You fire a transition, not a state​

POST /v1/projects/{project_id}/tasks/{task_id}/transitions takes a transition name. An undeclared name is a 400; a name that is not legal from the current state is a 409. Both come from the runtime, which is what makes the workflow the single source of truth about legal moves — PATCH /v1/projects/{project_id}/tasks/{task_id} edits the title, assignee and payload, and never the state. Model a process as a workflow fires revise to send a task back to an earlier state.

A task is pinned to a workflow version​

workflow_version is stamped at creation and never moves. Rewiring the workflow leaves in-flight tasks on the machine they started on.

Automation, and the loop bound​

If the entered state declares on_enter, the task dispatches it and reports progress through active_dispatch and automation_status. A dispatch may itself transition the task, which is recorded with principal_type: automation; automation_chain_depth counts how many such moves have run back-to-back, which is what stops a workflow from looping forever without a human or a client.

A dispatch runs under the authority the task stores: that of whoever last moved it, or of the run an automated move carries on. A task that stores none runs no tool: 409 WORK_AUTHORITY_MISSING.

A pause stops the automation, not the board​

POST /v1/projects/{project_id}/tasks/{task_id}/pause suppresses every dispatch a state would start — an agent generation, a tool call, an orchestration — and abandons a retry chain's remaining attempts, so the task stops spending without losing its place. Transitions keep working under it: a move costs nothing while the dispatch it would start is suppressed, so a board stays usable. A state entered under a pause records automation_status: paused, and POST /v1/projects/{project_id}/tasks/{task_id}/resume is the only thing that lifts one — it starts the dispatch the pause suppressed and leaves a state whose work had already completed alone.

A negative balance stops what a task would dispatch​

Entering a state can generate, so POST /v1/projects/{project_id}/tasks, POST /v1/projects/{project_id}/tasks/{task_id}/transitions and POST /v1/projects/{project_id}/tasks/{task_id}/resume answer 402 INSUFFICIENT_CREDIT and dispatch nothing while the project owes for usage already served. It is the project owner's balance. See A negative balance stops managed generation.

A Free account that has used its plan's monthly runs answers 403 PLAN_LIMIT_REACHED with resource: "runs" here as well, on its own credential too. See A plan's run allowance can stop generation.

This holds however the call arrives: a call to this API or an agent's tool call.

Only a move that would dispatch is refused: a create whose entry state (state, else the initial one) declares on_enter in the workflow's current version, a transition into a state whose on_enter is declared in the task's pinned workflow version (approval-gated or not), and a resume of a task whose automation_status is paused. A move into a state that only parks goes through. Reading, closing and pausing are never refused — a pause is how the debt stops growing.

An automation chain already dispatching is paused instead. A chain runs on nobody's request, so nothing can refuse it; the reconciliation that discovers the debt pauses every open task whose automation_status is running, with a pause_reason saying to top up. A task whose automation has come to rest is left alone, since what would start it again is a transition into a dispatching state, which is refused meanwhile.

Find a task by a field you keep in metadata​

GET /v1/projects/{project_id}/tasks takes ?metadata=, a JSON object url-encoded into one parameter, so a task carrying your own record id is found by it without keeping a map of task ids. The match is exact ({"external_id": 42} and {"external_id": "42"} are different filters); { "in": [...] } matches any listed value and gt, gte, lt, lte order a field by the operand's type. It narrows alongside state, status and assignee; malformed JSON or an operand with no order is 400 VALIDATION_FAILED. The same grammar filters documents.

Priority is a person's to set​

priority is very_high, high, medium, low, very_low, or null when nobody prioritised the task. Only PUT /v1/projects/{project_id}/tasks/{task_id}/priority sets it, and null clears it; create and update do not accept it. GET /v1/projects/{project_id}/tasks filters on priority (repeat it to OR values; none selects the unprioritised), and guards read it as task.priority.

?order=next lists in pull order: effective priority (the highest of the task and every open task it blocks, transitively; null lowest), then readiness.unblocks descending, then oldest in its state. It composes with every filter and answers one page: limit applies, a cursor is 400.

A task can wait on others​

POST /v1/projects/{project_id}/tasks/{task_id}/dependencies { depends_on_task_id, note? } makes the task wait on another in the project, across workflows: it is blocked while that task is open. A cycle is 409 TASK_DEPENDENCY_CYCLE (meta.path), the task itself 400 TASK_DEPENDENCY_SELF, and a closed task cannot gain one (409 TASK_DEPENDENCY_CLOSED). GET …/dependencies and GET …/dependents list both sides; DELETE …/dependencies/{depends_on_task_id} removes one.

Every read carries readiness (blocked, blocked_by, blocked_by_count, unblocks). Any close, cancelled included, frees what the task held. Readiness gates nothing on its own: a guard reads task.readiness.blocked to hold a transition, and ?blocked=true (or false) filters a board by it.

The history is the audit trail​

GET /v1/projects/{project_id}/tasks/{task_id}/history returns every move in order, each naming who made it and what caused it — the generation, the run or the tool. It is append-only. Model a process as a workflow reads one with a move back to an earlier state in it.

To follow a task without polling, subscribe a webhook to tasks.*: every creation, move, migration, close, stall, pause and automation outcome is delivered with the task as its GET reads it.

Who may do what​

Every route needs any project member.

Examples​

Open a task on a workflow​

naturali create-task \
--project-id proj_V1StGXR8Z5jdHi6B \
--workflow-id wfl_V1StGXR8Z5jdHi6B \
--title "Invoice 4471" \
--payload '{ "amount": 4200, "customer": "acme" }'

Find a task by your own record id​

naturali list-tasks \
--project-id proj_V1StGXR8Z5jdHi6B \
--metadata '{"source":"zendesk","external_id":"8123"}'

Move it through a declared transition​

naturali transition-task \
--project-id proj_V1StGXR8Z5jdHi6B \
--task-id task_V1StGXR8Z5jdHi6B \
--transition approve \
--note "under the 10k limit"

Read who moved it, and why​

naturali get-task-history \
--project-id proj_V1StGXR8Z5jdHi6B \
--task-id task_V1StGXR8Z5jdHi6B

Make a task wait on another​

naturali add-task-dependency \
--project-id proj_V1StGXR8Z5jdHi6B \
--task-id task_V1StGXR8Z5jdHi6B \
--depends-on-task-id task_3OmBu0xBaYp1Nq7C