Human Tasks
Read-only monitoring of durable workflow Human Tasks for external agents and API clients.
Endpoints for durable workflow Human Tasks under /api/v1/human-tasks. A Human Task is the
control-plane projection of a workflow run that has parked at an approval (Human Task) node: the
run's checkpoint and wait token remain the execution source of truth, and the task record models
lifecycle, assignment, work state, dates, and outcome.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/human-tasks | List tasks the caller is authorized for |
| GET | /api/v1/human-tasks/{id} | Get one authorized task projection |
Both require a workspace-scoped bearer API key. Authorization is resolved against the key owner's current workspace membership and task eligibility at request time (KTD9): a revoked or cross-workspace principal sees no task, even for a task issued earlier.
Listing tasks
GET /api/v1/human-tasks accepts these optional query params:
| Param | Description |
|---|---|
filter | eligible | mine | unassigned | open | due | overdue | completed |
runId | Restrict to tasks for one run |
limit | Max results, default 25, clamped 1–100 |
offset | Pagination offset; the response returns nextOffset (or null at the end) |
An unknown filter returns 400. The response is { tasks, nextOffset, links }, where links
maps each taskId to its detail path.
Task projection
Each task is a redacted summary. It never includes draft values, form contents, signal payloads, or resume secrets — only field presence flags and digestible metadata.
| Field | Meaning |
|---|---|
id | Task id |
workspaceId | Owning workspace |
workflowId, runId, nodeId | Linked workflow, run, and Human Task node |
taskType | Task kind (e.g. approval, form) |
lifecycleState | open | completed | canceled | expired |
workState | ready | started | paused (independent of lifecycle) |
priority | Task priority |
assigneeUserId | Current assignee, or null when unassigned |
eligibleRoles | Roles eligible to claim/complete |
outcomes | Named outcomes the completing human may select |
instructions | Reviewer instructions, or null |
dueAt, followUpAt, escalateAt | Due, follow-up, and escalation timestamps |
terminalOutcome | The winning outcome once terminal, else null |
hasFormSchema, hasFormDraft | Presence flags only — contents are never returned |
revision | Compare-and-set revision guarding concurrent transitions |
createdAt, updatedAt | Timestamps |
Lifecycle
Lifecycle is separate from assignment and work state. A task stays open while it is claimed,
reassigned, drafted, started, paused, reminded, or escalated; only a terminal transition consumes the
linked wait token exactly once:
completed— an eligible human selected a named outcome; the run resumes down that branch.canceled— the run or task was canceled.expired— a hard timeout elapsed; the run follows its configured timeout branch. An expired task is never silently treated as approval.
Reminders and escalations update task and audit state and notify the target, but they do not resume the run. When completion races a timeout or cancellation, one checkpoint compare-and-set wins and the loser receives a terminal conflict without a second resume.
Related
- Human-only session routes:
/api/human-tasks(claim, save draft, complete, reassign) and pending Agent tool confirmations at/api/human-tasks/agent-confirmations. - Recovery: see the durable Human Task recovery runbook.