---
title: "Retrieve a worker"
method: GET
path: "/api/workers/{workerId}"
tags: ["Workers"]
---

# Retrieve a worker

`GET /api/workers/{workerId}`

Retrieve the current worker state and messages from its most recent task (or a specific task via `taskId`).

## Path parameters

- `workerId` string, required

## Query parameters

- `taskId` string — Return the worker state and messages for a specific task instead of the most recent one.

## Response `200`

Worker object.

- Worker
  - `id` string, required
  - `object` 'worker', required
  - `created_at` integer, nullable, required
  - `status` 'running' | 'completed' | 'pending', required
  - `running` boolean, required
  - `error` unknown, required
  - `incomplete_details` unknown, required
  - `metadata` object, required
  - `output` object[], required
    - `id` string, required
    - `type` 'message', required
    - `role` 'assistant', required
    - `status` 'completed', required
    - `content` object[], required
      - `type` 'output_text', required
      - `text` string, required
  - `output_text` string, required
  - `structured_output` object, nullable, required
  - `sources` object[], required
    - `id` string, required
    - `type` 'url', required
    - `url` string, required
    - `title` string, nullable, required
  - `files` object[], required
    - `mediaType` string, required
    - `filename` string, nullable, required
    - `url` string, uri, required
    - `size` integer
  - `usage` object
    - `durationMs` integer
  - `messages` unknown[], required
    - unknown
  - `url` string, required — Web URL of the worker in the Handinger dashboard.

## Other responses

- `401` — Unauthorized.
- `403` — Forbidden.
- `429` — Rate limit exceeded.
- `500` — Internal server error.

---

[API](https://skmtc.net/ramensoft/apis/handinger-api.md) · [All operations](https://skmtc.net/ramensoft/apis/handinger-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ramensoft/handinger-api/versions/95b6b61a63ef/schema)