Skip to content
Handinger
Get started
API Reference
Tasks

Retrieve a task with its turns

GET/api/tasks/{taskId}

Retrieve a single task and its individual turns.

Path ParametersExpand Collapse
taskId: string
ReturnsExpand Collapse
TaskWithTurns object { task, turns }
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
turns: array of object { id, completedAt, credits, 11 more }
id: string
completedAt: string
credits: number
durationMs: number
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

Retrieve a task with its turns

curl https://handinger.com/api/tasks/$TASK_ID \
    -H "Authorization: Bearer $HANDINGER_API_KEY"
{
  "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"
  },
  "turns": [
    {
      "id": "trn_4Hq-9Vk2pLm8Rx",
      "completedAt": "2026-05-11T09:14:48.000Z",
      "credits": 42,
      "durationMs": 25812,
      "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": "user",
      "seq": 0,
      "startedAt": "2026-05-11T09:14:22.000Z",
      "status": "completed",
      "structuredOutput": {
        "temperatureCelsius": "bar",
        "conditions": "bar"
      },
      "taskId": "tsk_2Z-YWz3hFq6VlW"
    }
  ]
}
Returns Examples
{
  "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"
  },
  "turns": [
    {
      "id": "trn_4Hq-9Vk2pLm8Rx",
      "completedAt": "2026-05-11T09:14:48.000Z",
      "credits": 42,
      "durationMs": 25812,
      "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": "user",
      "seq": 0,
      "startedAt": "2026-05-11T09:14:22.000Z",
      "status": "completed",
      "structuredOutput": {
        "temperatureCelsius": "bar",
        "conditions": "bar"
      },
      "taskId": "tsk_2Z-YWz3hFq6VlW"
    }
  ]
}