Skip to content

Retrieve a task with its turns

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

GET/api/tasks/{taskId}

Retrieve a single task and its individual turns.

ParametersExpand Collapse

task_id: String

ReturnsExpand Collapse

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

Retrieve a task with its turns

require "handinger"

handinger = Handinger::Client.new(api_key: "My API Key")

task_with_turns = handinger.tasks.retrieve("tsk_01HZY31W2SZJ8MJ2FQTR3M1K9D")

puts(task_with_turns)

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