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

client.tasks.create(TaskCreateParams { input, budget, taskId, workerId } body, RequestOptionsoptions?): Worker { id, created_at, error, 13 more }

POST/api/tasks

Retrieve a task

client.tasks.retrieve(stringtaskID, RequestOptionsoptions?): TaskRetrieveResponse { task }

GET/api/tasks/{taskId}

List task turns

client.tasks.listTurns(stringtaskID, RequestOptionsoptions?): TaskTurnList { items, taskId }

GET/api/tasks/{taskId}/turns

Archive a task

client.tasks.delete(stringtaskID, RequestOptionsoptions?): DeleteTaskResponse { archived }

DELETE/api/tasks/{taskId}

ModelsExpand Collapse

CreateTask { input, budget, taskId, workerId }

input: string

minLength1

budget?: "low" | "standard" | "high" | "unlimited"

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

One of the following:

"low"

"standard"

"high"

"unlimited"

taskId?: string

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

minLength1

workerId?: string

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

minLength1

DeleteTaskResponse { archived }

archived: boolean

Task { id, completedAt, createdAt, 8 more }

id: string

completedAt: string | null

createdAt: string

createdByUserId: string | null

organizationId: string

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

One of the following:

"pending"

"running"

"completed"

"error"

"aborted"

title: string

totals: Totals { credits, durationMs, turnCount }

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

credits: number

durationMs: number

turnCount: number

triggeredBy: "api" | "email" | "schedule" | "ui"

One of the following:

"api"

"email"

"schedule"

"ui"

url: string

Web URL of the task in the Handinger dashboard.

workerId: string

TaskTurnList { items, taskId }

items: Array<Turn { id, completedAt, credits, 12 more } >

id: string

completedAt: string | null

credits: number

durationMs: number

files: Array<File>

Files published by this turn.

filename: string | null

mediaType: string

url: string

formaturi

size?: number

minimum0

input: string

inputTokens: number

outputText: string

outputTokens: number

role: string

seq: number

startedAt: string

status: string

structuredOutput: Record<string, unknown> | null

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

taskId: string

taskId: string

Turn { id, completedAt, credits, 12 more }

id: string

completedAt: string | null

credits: number

durationMs: number

files: Array<File>

Files published by this turn.

filename: string | null

mediaType: string

url: string

formaturi

size?: number

minimum0

input: string

inputTokens: number

outputText: string

outputTokens: number

role: string

seq: number

startedAt: string

status: string

structuredOutput: Record<string, unknown> | null

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

taskId: string

TaskRetrieveResponse { task }

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

id: string

completedAt: string | null

createdAt: string

createdByUserId: string | null

organizationId: string

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

One of the following:

"pending"

"running"

"completed"

"error"

"aborted"

title: string

totals: Totals { credits, durationMs, turnCount }

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

credits: number

durationMs: number

turnCount: number

triggeredBy: "api" | "email" | "schedule" | "ui"

One of the following:

"api"

"email"

"schedule"

"ui"

url: string

Web URL of the task in the Handinger dashboard.

workerId: string