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

tasks.create(**kwargs) -> Worker { id, created_at, error, 13 more }

POST/api/tasks

Retrieve a task with its turns

tasks.retrieve(task_id) -> TaskWithTurns { task, turns }

GET/api/tasks/{taskId}

Archive a task

tasks.delete(task_id) -> DeleteTaskResponse { archived }

DELETE/api/tasks/{taskId}

ModelsExpand Collapse

class CreateTask { input, budget, task_id, worker_id }

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

task_id: String

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

minLength1

worker_id: String

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

minLength1

class DeleteTaskResponse { archived }

archived: bool

class Task { id, completed_at, created_at, 8 more }

id: String

completed_at: String

created_at: String

created_by_user_id: String

organization_id: String

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

One of the following:

:pending

:running

:completed

:error

:aborted

title: String

totals: Totals{ credits, duration_ms, turn_count}

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

credits: Integer

duration_ms: Integer

turn_count: Integer

triggered_by: :api | :email | :schedule | :ui

One of the following:

:api

:email

:schedule

:ui

url: String

Web URL of the task in the Handinger dashboard.

worker_id: String

class TaskWithTurns { task, turns }

task: Task { id, completed_at, created_at, 8 more }

id: String

completed_at: String

created_at: String

created_by_user_id: String

organization_id: String

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

One of the following:

:pending

:running

:completed

:error

:aborted

title: String

totals: Totals{ credits, duration_ms, turn_count}

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

credits: Integer

duration_ms: Integer

turn_count: Integer

triggered_by: :api | :email | :schedule | :ui

One of the following:

:api

:email

:schedule

:ui

url: String

Web URL of the task in the Handinger dashboard.

worker_id: String

turns: Array[Turn{ id, completed_at, credits, 11 more}]

id: String

completed_at: String

credits: Integer

duration_ms: Integer

input: String

input_tokens: Integer

output_text: String

output_tokens: Integer

role: String

seq: Integer

started_at: String

status: String

structured_output: Hash[Symbol, untyped]

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

task_id: String