# Tasks ## Create a task `tasks.create(TaskCreateParams**kwargs) -> Worker` **post** `/api/tasks` Run a new task against an existing worker and wait for the result. Send a `taskId` of a prior task to add a follow-up turn instead of starting a fresh task. Send `multipart/form-data` to attach files; the bytes are bootstrapped into the worker's workspace before the task starts. The task runs to completion on the server even if the connection drops; subscribe to task webhooks for long-running tasks. ### Parameters - `input: str` - `budget: Optional[Literal["low", "standard", "high", "unlimited"]]` Compute budget the worker is allowed to spend on the task. Defaults to `standard`. - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `task_id: Optional[str]` Optional client-provided task id. Reuse this id to add turns to an existing task. - `worker_id: Optional[str]` Worker id the task belongs to. If omitted, a new worker is created on-the-fly using the input as instructions. ### Returns - `class Worker: …` - `id: str` - `created_at: Optional[int]` - `error: None` - `files: List[File]` - `filename: Optional[str]` - `media_type: str` - `url: str` - `size: Optional[int]` - `incomplete_details: None` - `messages: List[object]` - `metadata: Dict[str, object]` - `object: Literal["worker"]` - `"worker"` - `output: List[Output]` - `id: str` - `content: List[OutputContent]` - `text: str` - `type: Literal["output_text"]` - `"output_text"` - `role: Literal["assistant"]` - `"assistant"` - `status: Literal["completed"]` - `"completed"` - `type: Literal["message"]` - `"message"` - `output_text: str` - `running: bool` - `sources: List[Source]` - `id: str` - `title: Optional[str]` - `type: Literal["url"]` - `"url"` - `url: str` - `status: Literal["running", "completed", "pending"]` - `"running"` - `"completed"` - `"pending"` - `structured_output: Optional[Dict[str, object]]` - `url: str` Web URL of the worker in the Handinger dashboard. - `usage: Optional[Usage]` - `duration_ms: Optional[int]` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) worker = client.tasks.create( input="What's the weather today in Barcelona?", worker_id="wrk_vk81XUHKHG-qr4", ) print(worker.id) ``` #### Response ```json { "id": "id", "created_at": 0, "error": null, "files": [ { "filename": "filename", "mediaType": "mediaType", "url": "https://example.com", "size": 0 } ], "incomplete_details": null, "messages": [ {} ], "metadata": { "foo": "bar" }, "object": "worker", "output": [ { "id": "id", "content": [ { "text": "text", "type": "output_text" } ], "role": "assistant", "status": "completed", "type": "message" } ], "output_text": "output_text", "running": true, "sources": [ { "id": "id", "title": "title", "type": "url", "url": "url" } ], "status": "running", "structured_output": { "foo": "bar" }, "url": "https://v3.handinger.com/worker/wrk_vk81XUHKHG-qr4", "usage": { "durationMs": 0 } } ``` ## Retrieve a task `tasks.retrieve(strtask_id) -> TaskRetrieveResponse` **get** `/api/tasks/{taskId}` Retrieve a single task. ### Parameters - `task_id: str` ### Returns - `class TaskRetrieveResponse: …` - `task: Task` - `id: str` - `completed_at: Optional[str]` - `created_at: str` - `created_by_user_id: Optional[str]` - `organization_id: str` - `status: Literal["pending", "running", "completed", 2 more]` - `"pending"` - `"running"` - `"completed"` - `"error"` - `"aborted"` - `title: str` - `totals: Totals` Aggregate credit spend, elapsed wall-clock, and number of turns across the task. - `credits: int` - `duration_ms: int` - `turn_count: int` - `triggered_by: Literal["api", "email", "schedule", "ui"]` - `"api"` - `"email"` - `"schedule"` - `"ui"` - `url: str` Web URL of the task in the Handinger dashboard. - `worker_id: str` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) task = client.tasks.retrieve( "tsk_01HZY31W2SZJ8MJ2FQTR3M1K9D", ) print(task.task) ``` #### Response ```json { "task": { "id": "tsk_2Z-YWz3hFq6VlW", "completedAt": "2026-05-11T09:14:48.000Z", "createdAt": "2026-05-11T09:14:22.000Z", "createdByUserId": "usr_7yh-91XzM2nQ4", "organizationId": "org_8s1Df9aLp-1z", "status": "completed", "title": "Weather report for Barcelona", "totals": { "credits": 42, "durationMs": 25812, "turnCount": 1 }, "triggeredBy": "api", "url": "https://v3.handinger.com/worker/wrk_vk81XUHKHG-qr4/task/tsk_2Z-YWz3hFq6VlW", "workerId": "wrk_vk81XUHKHG-qr4" } } ``` ## List task turns `tasks.list_turns(strtask_id) -> TaskTurnList` **get** `/api/tasks/{taskId}/turns` List the individual turns for a task in execution order. ### Parameters - `task_id: str` ### Returns - `class TaskTurnList: …` - `items: List[Turn]` - `id: str` - `completed_at: Optional[str]` - `credits: int` - `duration_ms: int` - `files: List[File]` Files published by this turn. - `filename: Optional[str]` - `media_type: str` - `url: str` - `size: Optional[int]` - `input: str` - `input_tokens: int` - `output_text: str` - `output_tokens: int` - `role: str` - `seq: int` - `started_at: str` - `status: str` - `structured_output: Optional[Dict[str, object]]` Structured JSON payload when the worker is configured with an output schema. `null` otherwise. - `task_id: str` - `task_id: str` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) task_turn_list = client.tasks.list_turns( "tsk_01HZY31W2SZJ8MJ2FQTR3M1K9D", ) print(task_turn_list.items) ``` #### Response ```json { "items": [ { "id": "trn_4Hq-9Vk2pLm8Rx", "completedAt": "2026-05-11T09:14:48.000Z", "credits": 42, "durationMs": 25812, "files": [ { "filename": "filename", "mediaType": "mediaType", "url": "https://example.com", "size": 0 } ], "input": "What's the weather today in Barcelona?", "inputTokens": 1842, "outputText": "It's currently 21°C and sunny in Barcelona with a light breeze from the south-east.", "outputTokens": 312, "role": "assistant", "seq": 0, "startedAt": "2026-05-11T09:14:22.000Z", "status": "completed", "structuredOutput": { "temperatureCelsius": "bar", "conditions": "bar" }, "taskId": "tsk_2Z-YWz3hFq6VlW" } ], "taskId": "tsk_2Z-YWz3hFq6VlW" } ``` ## Archive a task `tasks.delete(strtask_id) -> DeleteTaskResponse` **delete** `/api/tasks/{taskId}` Archive a task so it stops appearing in `GET /tasks` results. Turns and files are retained for audit purposes. Only the worker creator can archive a task. ### Parameters - `task_id: str` ### Returns - `class DeleteTaskResponse: …` - `archived: bool` ### Example ```python import os from handinger import Handinger client = Handinger( api_key=os.environ.get("HANDINGER_API_KEY"), # This is the default and can be omitted ) delete_task_response = client.tasks.delete( "tsk_01HZY31W2SZJ8MJ2FQTR3M1K9D", ) print(delete_task_response.archived) ``` #### Response ```json { "archived": true } ``` ## Domain Types ### Create Task - `class CreateTask: …` - `input: str` - `budget: Optional[Literal["low", "standard", "high", "unlimited"]]` Compute budget the worker is allowed to spend on the task. Defaults to `standard`. - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `task_id: Optional[str]` Optional client-provided task id. Reuse this id to add turns to an existing task. - `worker_id: Optional[str]` Worker id the task belongs to. If omitted, a new worker is created on-the-fly using the input as instructions. ### Delete Task Response - `class DeleteTaskResponse: …` - `archived: bool` ### Task - `class Task: …` - `id: str` - `completed_at: Optional[str]` - `created_at: str` - `created_by_user_id: Optional[str]` - `organization_id: str` - `status: Literal["pending", "running", "completed", 2 more]` - `"pending"` - `"running"` - `"completed"` - `"error"` - `"aborted"` - `title: str` - `totals: Totals` Aggregate credit spend, elapsed wall-clock, and number of turns across the task. - `credits: int` - `duration_ms: int` - `turn_count: int` - `triggered_by: Literal["api", "email", "schedule", "ui"]` - `"api"` - `"email"` - `"schedule"` - `"ui"` - `url: str` Web URL of the task in the Handinger dashboard. - `worker_id: str` ### Task Turn List - `class TaskTurnList: …` - `items: List[Turn]` - `id: str` - `completed_at: Optional[str]` - `credits: int` - `duration_ms: int` - `files: List[File]` Files published by this turn. - `filename: Optional[str]` - `media_type: str` - `url: str` - `size: Optional[int]` - `input: str` - `input_tokens: int` - `output_text: str` - `output_tokens: int` - `role: str` - `seq: int` - `started_at: str` - `status: str` - `structured_output: Optional[Dict[str, object]]` Structured JSON payload when the worker is configured with an output schema. `null` otherwise. - `task_id: str` - `task_id: str` ### Turn - `class Turn: …` - `id: str` - `completed_at: Optional[str]` - `credits: int` - `duration_ms: int` - `files: List[File]` Files published by this turn. - `filename: Optional[str]` - `media_type: str` - `url: str` - `size: Optional[int]` - `input: str` - `input_tokens: int` - `output_text: str` - `output_tokens: int` - `role: str` - `seq: int` - `started_at: str` - `status: str` - `structured_output: Optional[Dict[str, object]]` Structured JSON payload when the worker is configured with an output schema. `null` otherwise. - `task_id: str` ### Task Retrieve Response - `class TaskRetrieveResponse: …` - `task: Task` - `id: str` - `completed_at: Optional[str]` - `created_at: str` - `created_by_user_id: Optional[str]` - `organization_id: str` - `status: Literal["pending", "running", "completed", 2 more]` - `"pending"` - `"running"` - `"completed"` - `"error"` - `"aborted"` - `title: str` - `totals: Totals` Aggregate credit spend, elapsed wall-clock, and number of turns across the task. - `credits: int` - `duration_ms: int` - `turn_count: int` - `triggered_by: Literal["api", "email", "schedule", "ui"]` - `"api"` - `"email"` - `"schedule"` - `"ui"` - `url: str` Web URL of the task in the Handinger dashboard. - `worker_id: str`