## Retrieve a task with its turns

**get** `/api/tasks/{taskId}`

Retrieve a single task and its individual turns.

### Path Parameters

- `taskId: string`

### Returns

- `TaskWithTurns object { task, turns }`

  - `task: Task`

    - `id: string`

    - `completedAt: string`

    - `createdAt: string`

    - `createdByUserId: string`

    - `organizationId: string`

    - `status: "pending" or "running" or "completed" or 2 more`

      - `"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"`

      - `"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`

### Example

```http
curl https://handinger.com/api/tasks/$TASK_ID \
    -H "Authorization: Bearer $HANDINGER_API_KEY"
```

#### 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"
  },
  "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"
    }
  ]
}
```