Tasks

Pause a task

Pauses a task's automation. While a pause is in force no state's on_enter dispatches and no retry chain continues — an agent generation, a tool call and a sub-orchestration alike — so the task stops spending without losing its place. A workflow has no run object, so this is the workflow half of pause-orchestration-run: the pause lands on the instance, which is the task. Transitions are deliberately still allowed — a move costs nothing while every dispatch it would start is suppressed — so a board stays usable under a pause. Entering a state whose dispatch is suppressed records automation_status: paused, which resume-task reads to know that state still owes its work. A dispatch already in flight is left to finish, and its outcome still routes; only what would start after it is suppressed. Idempotent: pausing an already-paused task answers with it unchanged.

post/v1/projects/{project_id}/tasks/{task_id}/pause

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/tasks/{task_id}/pause
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

task_idstring required

Request body

reasonstring

Why the task is being paused, surfaced on pause_reason.

Response

The paused task

idstring
project_idstring
workflow_idstring
workflow_versioninteger nullable

The 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
status'open' | 'closed'
payloadobject

Caller-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.

metadataMetadataBag

Caller-owned annotations on a resource, stored as the object they were written as: the types a value was written with are the types a read returns, so a filter can ask an ordering question about a number. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.

No key is reserved, and that is the point: every piece of state the platform owns lives in its own typed column, so nothing written here reaches platform state. The platform never reads the bag — it is not an IAM context, not a policy input and not part of a prompt — which is what separates it from a tag bag.

last_resultunknown
assigneestring nullable
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_status'running' | 'completed' | 'failed' | 'unrouted' | 'paused' | 'null' nullable

Status 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 nullable

When an operator paused this task's automation, or null when no pause is in force.

pause_reasonstring nullable

The reason supplied with the pause, when one was.

automation_chain_depthinteger

Server-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 with its run-as token. 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 nullable

The 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.

entered_state_atstring date-time
created_atstring date-time
updated_atstring date-time

Example response

{
  "workflow_version": 1,
  "metadata": {
    "author": "John",
    "revision": 2
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.