API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Tasks

Run and inspect tasks against a worker.

Create a task

POST/api/tasks

Retrieve a task

GET/api/tasks/{taskId}

List task turns

GET/api/tasks/{taskId}/turns

Archive a task

DELETE/api/tasks/{taskId}

ModelsExpand Collapse

CreateTask object { input, budget, taskId, workerId }

input: string

minLength1

budget: optional "low" or "standard" or "high" or "unlimited"

Compute budget the worker is allowed to spend on the task. Defaults to standard.

One of the following:

"low"

"standard"

"high"

"unlimited"

taskId: optional string

Optional client-provided task id. Reuse this id to add turns to an existing task.

minLength1

workerId: optional string

Worker id the task belongs to. If omitted, a new worker is created on-the-fly using the input as instructions.

minLength1

DeleteTaskResponse object { archived }

archived: boolean

Task object { id, completedAt, createdAt, 8 more }

id: string

completedAt: string

createdAt: string

createdByUserId: string

organizationId: string

status: "pending" or "running" or "completed" or 2 more

One of the following:

"pending"

"running"

"completed"

"error"

"aborted"

title: string

totals: object { credits, durationMs, turnCount }

Aggregate credit spend, elapsed wall-clock, and number of turns across the task.

credits: number

durationMs: number

turnCount: number

triggeredBy: "api" or "email" or "schedule" or "ui"

One of the following:

"api"

"email"

"schedule"

"ui"

url: string

Web URL of the task in the Handinger dashboard.

workerId: string

TaskTurnList object { items, taskId }

items: array of Turn { id, completedAt, credits, 12 more }

id: string

completedAt: string

credits: number

durationMs: number

files: array of object { filename, mediaType, url, size }

Files published by this turn.

filename: string

mediaType: string

url: string

formaturi

size: optional number

minimum0

input: string

inputTokens: number

outputText: string

outputTokens: number

role: string

seq: number

startedAt: string

status: string

structuredOutput: map[unknown]

Structured JSON payload when the worker is configured with an output schema. null otherwise.

taskId: string

taskId: string

Turn object { id, completedAt, credits, 12 more }

id: string

completedAt: string

credits: number

durationMs: number

files: array of object { filename, mediaType, url, size }

Files published by this turn.

filename: string

mediaType: string

url: string

formaturi

size: optional number

minimum0

input: string

inputTokens: number

outputText: string

outputTokens: number

role: string

seq: number

startedAt: string

status: string

structuredOutput: map[unknown]

Structured JSON payload when the worker is configured with an output schema. null otherwise.

taskId: string

TaskRetrieveResponse object { task }

task: Task { id, completedAt, createdAt, 8 more }

id: string

completedAt: string

createdAt: string

createdByUserId: string

organizationId: string

status: "pending" or "running" or "completed" or 2 more

One of the following:

"pending"

"running"

"completed"

"error"

"aborted"

title: string

totals: object { credits, durationMs, turnCount }

Aggregate credit spend, elapsed wall-clock, and number of turns across the task.

credits: number

durationMs: number

turnCount: number

triggeredBy: "api" or "email" or "schedule" or "ui"

One of the following:

"api"

"email"

"schedule"

"ui"

url: string

Web URL of the task in the Handinger dashboard.

workerId: string