Skip to main content
GET
Get a human task
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Reads one human task as the Personal key’s owner sees it in the Forge Console: its prompt and v2 form with the actions that answer it, what was decided (actionTaken, output, completionReason) or why it was canceled, and what the owner may do (claimable, canTakeOver).

Who sees a task

The owner sees a task that asks them (isCandidate), one they watch, or one they asked for. An owner who holds approvals:approve at the task’s home also sees a hold or a workflow step they may take over (canTakeOver, with its reassignRef) — but only through a key whose scopes reach approvals:approve: a key carrying approvals:read alone never reports take-over. A review queue’s group task asks everyone who holds the queue’s permission at the platform scope now, through the key’s scopes; the owner may take over its claim when they also hold approvals:approve at the platform scope, and its reassignRef is { "kind": "human_task", "id": <task id> }. A task the owner may not see, a missing task and a malformed id all answer the same 404. A platform key or an External App gets 403 with error.personRequired: true. See Person-relative reads.

Parameters

Example

The response is { "data": { "humanTask": { … } }, "meta": { "requestId": "…" } }; humanTask follows the HumanTaskView schema. The MCP tool forge_get_human_task returns the same data and meta.

Authorizations

Authorization
string
header
required

A Personal key (fmcp_…), bound to the person who created it, or an interactive MCP sign-in that resolves to one. Pass as Authorization: Bearer <key>. It acts for that person, under their role grants narrowed by its scopes; an operation that acts for a person admits only this kind.

Path Parameters

humanTaskId
string
required

The human task id (humanTaskId on a My Work item).

Minimum string length: 1

Response

The task

data
object
required
meta
object
required