API Reference

Tasks

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve a task

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

GET/api/tasks/{taskId}

Retrieve a single task.

ParametersExpand Collapse

taskID: string

ReturnsExpand Collapse

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

Retrieve a task

TypeScript

HTTP

TypeScript

Python

Go

Ruby

CLI Tool

import Handinger from '@ramensoft/handinger';

const client = new Handinger({
  apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted
});

const task = await client.tasks.retrieve('tsk_01HZY31W2SZJ8MJ2FQTR3M1K9D');

console.log(task.task);

200 example

{
  "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"
  }
}

Returns Examples

200 example

{
  "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"
  }
}