# Computers

List and read the computers workers use, set up the workspace's Linux computer, and read and stop the work on a computer.

A computer is where a worker's commands, browser and files run. A workspace can have one active Linux computer, which Little Worker runs for it, and one Mac that a person paired in the Little Worker Mac app. A task does not pick its computer. A worker's first tool call that needs a computer uses the workspace's own, and the tools that act on a Mac go to the Mac a person paired. A task's `computer_id` shows the computer it last ran on.

These routes list and read computers, set up the Linux computer, change a computer's name, description, labels and packages, archive or delete one, and read and stop the work on one. A work record is one running stretch of a task on a computer. It opens at the task's first call there. It is `stopped` once the task's run has ended, or a stop was asked for, and none of its calls is open. The task's next call opens a new record. A task that never uses the computer has no record. [Computers](/concepts/computers) explains the two kinds and the work records.

> [!NOTE]
> A computer is an environment in Claude Managed Agents, and a work record is a work item of a self-hosted environment. Here a Mac joins when a person pairs it, so `POST /computers` makes only the Linux computer, and a computer's `networking` is read only.

## The computer object

Most routes on this page answer a computer, or a list of them. The routes under `/work` answer work records and queue counts, which have their own fields under [Read the work queue](#read-the-work-queue) and [Read a work record](#read-a-work-record). Times are RFC 3339 in UTC, to the millisecond.

- `type` (string): Always `computer`.

- `id` (computer id): The computer's id: `computer_` and 32 hex digits. A Linux computer and a Mac have ids of the same form.

- `scope` (string): Always `organization`: computers are shared by the workspace.

- `name` (string): The computer's name. A Linux computer that was never named is `Computer`, and a Mac that was never named has the name it was paired under.

- `description` (string): What the computer is for. Empty when unset.

- `metadata` (object): Your own labels for the computer: up to 16 keys of 1 to 64 characters, each with a string value of up to 512.

- `status` (string): Where the computer stands. A Linux computer is `provisioning` while it is made, `ready` when it can take work, `stopping` and `stopped` when it is shut down, `starting` while it starts again, `recovering` when Little Worker could not confirm a step on the machine, or `failed`. Little Worker stops a Linux computer after 15 idle minutes and starts it again when a task needs it. A Mac is `enrolled` while it is paired, and `revoked` once it is archived or deleted. One of `provisioning`, `ready`, `stopping`, `stopped`, `starting`, `recovering`, `failed`, `enrolled`, `revoked`.

- `config` (object): Where the computer runs. A Linux computer is `cloud` and also holds its `networking` and `packages`. A Mac is `self_hosted` and holds only its `type`.

  - `type` (string): `cloud` for the Linux computer Little Worker runs for the workspace, `self_hosted` for a Mac a person paired. One of `cloud`, `self_hosted`.

  - `networking` (object): Only on a `cloud` computer, and read only. The websites a worker may reach are set on the worker's `networking`, not here.

    - `type` (string): Always `limited`.

    - `allowed_hosts` (array of strings): Always empty.

    - `allow_mcp_servers` (boolean): Always `true`: Little Worker calls apps itself, so the computer never needs to reach them.

    - `allow_package_managers` (boolean): `true` when the computer lists packages to install.

  - `packages` (object): Only on a `cloud` computer. What it installs before work, by package manager.

    - `type` (string): Always `packages`.

    - `apt` (array of strings): The packages installed with `apt`. Empty when none.

    - `cargo` (array of strings): The packages installed with `cargo`. Empty when none.

    - `gem` (array of strings): The packages installed with `gem`. Empty when none.

    - `go` (array of strings): The packages installed with `go`. Empty when none.

    - `npm` (array of strings): The packages installed with `npm`. Empty when none.

    - `pip` (array of strings): The packages installed with `pip`. Empty when none.

- `created_at` (time): When the computer was made, or the Mac was paired.

- `updated_at` (time): When the computer's record last changed. It moves each time the computer reports in, so it does not mean someone edited the computer.

- `archived_at` (time, or null): When the computer was archived. `null` while it is not.

```json
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "ready",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-25T08:40:17.904Z",
  "archived_at": null
}
```

## List computers

`GET /computers`

List the computers in the key's workspace: the Linux computer when there is one, and the Mac a person paired. They come newest first by default. Archived computers are left out unless you ask for them. On a shared workspace, a Mac is listed only for the person who paired it.

### Query parameters

- `limit` (integer): How many to answer, 1 to 1,000. The default is 20.
- `page` (string): The `next_page` of the answer before, to read the next page.
- `order` (string): `desc`, newest first (the default), or `asc`, oldest first. One of `desc`, `asc`.
- `created_at[gt]` (time): Only those made after this time, an RFC 3339 time compared to the millisecond the answer shows. `created_at[gte]`, `created_at[lt]` and `created_at[lte]` work the same way.
- `include_archived` (string): `true` lists archived computers too. The default is `false`. One of `true`, `false`.

### Returns

A list: `data` holds the computers, and `next_page` is the `page` to send for the next ones (`null` on the last page).

### Example

```bash
curl "https://core.thelittleworker.com/api/v1/computers?limit=10" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
```

```json
{
  "data": [
    {
      "type": "computer",
      "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
      "scope": "organization",
      "name": "Workspace computer",
      "description": "Runs the shop's tasks.",
      "metadata": {
        "team": "ops"
      },
      "status": "ready",
      "config": {
        "type": "cloud",
        "networking": {
          "type": "limited",
          "allowed_hosts": [],
          "allow_mcp_servers": true,
          "allow_package_managers": true
        },
        "packages": {
          "type": "packages",
          "apt": [
            "graphviz"
          ],
          "cargo": [],
          "gem": [],
          "go": [],
          "npm": [],
          "pip": [
            "pandas==2.2.0"
          ]
        }
      },
      "created_at": "2026-10-20T09:14:02.331Z",
      "updated_at": "2026-10-25T08:40:17.904Z",
      "archived_at": null
    },
    {
      "type": "computer",
      "id": "computer_9b7e3c1a5d2f4a8e8c6b0d4f2a1e7c35",
      "scope": "organization",
      "name": "Sam's MacBook Pro",
      "description": "",
      "metadata": {},
      "status": "enrolled",
      "config": {
        "type": "self_hosted"
      },
      "created_at": "2026-10-12T15:22:48.017Z",
      "updated_at": "2026-10-25T16:03:51.642Z",
      "archived_at": null
    }
  ],
  "next_page": null
}
```

### Errors

- 400 `invalid_request_error`: A query value is not valid, such as a `limit` outside 1 to 1,000 or an `include_archived` that is not `true` or `false` (`error_code` `validation_error`). `page` is not a page this list gave with the same `order` and `created_at` filters (`error_code` `invalid_cursor`). Read the first page again.
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## Set up the Linux computer

`POST /computers`

Set up the workspace's Linux computer, with its name and the packages it installs before work. A workspace has one active Linux computer, so a second call is refused until the first is archived or deleted. A Mac cannot be made here: a person pairs it in the Mac app.

The answer comes after the machine is made, so `status` is normally `ready`. It is `recovering` when Little Worker could not confirm the machine or could not finish setting it up. Read the computer again to see it change. Packages are installed when the computer is made, started or recreated.

### Body

- `name` (string, required): The computer's name, 1 to 256 characters.
- `config` (object, required): Where the computer runs.
  - `type` (string, required): `cloud` for the Linux computer. `self_hosted` is refused: a Mac joins when a person pairs it. One of `cloud`, `self_hosted`.
  - `packages` (object): What to install before work. A manager you leave out lists nothing.
    - `type` (string): Always `packages` when you send it. A computer's own `packages` has it, so you may send that back as it is.
    - `apt` (array of strings): The packages to install with `apt`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `cargo` (array of strings): The packages to install with `cargo`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `gem` (array of strings): The packages to install with `gem`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `go` (array of strings): The packages to install with `go`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `npm` (array of strings): The packages to install with `npm`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `pip` (array of strings): The packages to install with `pip`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
  - `networking` (object): Refused. A computer's `networking` is read only; set the websites a worker may reach on the worker.
- `description` (string): What the computer is for, up to 2,048 characters.
- `metadata` (object): Your own labels: up to 16 keys of 1 to 64 characters, each with a string value of up to 512.
- `scope` (string): `organization`, the only scope a computer has. `account` is refused. One of `organization`, `account`.

### Returns

`200` and the computer.

### Example

```bash
curl "https://core.thelittleworker.com/api/v1/computers" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19" \
  -H "content-type: application/json" \
  -d '{
  "name": "Workspace computer",
  "description": "Runs the shop'\''s tasks.",
  "config": {
    "type": "cloud",
    "packages": {
      "apt": [
        "graphviz"
      ],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "metadata": {
    "team": "ops"
  }
}'
```

```json
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "ready",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-20T09:14:04.870Z",
  "archived_at": null
}
```

### Errors

- 400 `invalid_request_error`: A field is missing or not valid, or one is refused (`error_code` `validation_error`): `config.type` is `self_hosted`, `scope` is `account`, or `config.networking` is sent. `message` says which.
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 409 `conflict_error`: The workspace already has a Linux computer (`error_code` `computer_conflict`). Archive or delete it before you make another. A workspace whose subscription does not include a computer on Little Worker's servers is refused with `error_code` `conflict` and the message `A hosted computer is not available.`
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## Read a computer

`GET /computers/{computer_id}`

Read one computer as it stands now, archived or not. A deleted computer is gone.

### Path parameters

- `computer_id` (computer id, required): The computer, such as `computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21`. A Mac has an id of the same form.

### Returns

The computer.

### Example

```bash
curl https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21 \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
```

```json
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "ready",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-25T08:40:17.904Z",
  "archived_at": null
}
```

### Errors

- 400 `invalid_request_error`: `computer_id` is not a computer id. `error_code` is `validation_error`.
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 404 `not_found_error`: No computer in the key's workspace has this id (`Computer not found.`), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## Change a computer

`POST /computers/{computer_id}`

Change a computer's name, description, labels or packages. A field left out stays as it was. A `metadata` key with a string is set, a key set to `null` is removed, and keys left out stay. An archived computer takes no change.

A Linux computer's `packages` replace the ones it had, so send every package you want to keep. A manager you leave out is emptied. The new packages are installed the next time the computer starts or is recreated. A Mac installs no packages.

### Path parameters

- `computer_id` (computer id, required): The computer, such as `computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21`. A Mac has an id of the same form.

### Body

- `name` (string): A new name, 1 to 256 characters.
- `description` (string): A new description, up to 2,048 characters.
- `metadata` (object): Labels to set, up to 16 keys of 1 to 64 characters, each with a string value of up to 512 or `null`. A key set to `null` is removed. The computer may not hold more than 16 keys after the change.
- `config` (object): Settings of where the computer runs.
  - `packages` (object): The packages to install, which replace the old ones. Linux computer only.
    - `type` (string): Always `packages` when you send it. A computer's own `packages` has it, so you may send that back as it is.
    - `apt` (array of strings): The packages to install with `apt`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `cargo` (array of strings): The packages to install with `cargo`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `gem` (array of strings): The packages to install with `gem`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `go` (array of strings): The packages to install with `go`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `npm` (array of strings): The packages to install with `npm`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
    - `pip` (array of strings): The packages to install with `pip`: up to 100, each a name of 1 to 256 characters that starts with a letter, a digit or `@` and has no spaces, quotes or shell characters, with a version if you want one, such as `pandas==2.2.0`. Left out, none.
  - `type` (string): If you send it, it must be the computer's own `config.type`. It cannot change. One of `cloud`, `self_hosted`.
  - `networking` (object): Refused. A computer's `networking` is read only; set the websites a worker may reach on the worker.

### Returns

The computer, changed.

### Example

```bash
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19" \
  -H "content-type: application/json" \
  -d '{
  "description": "Runs the shop'\''s tasks.",
  "metadata": {
    "team": "ops"
  },
  "config": {
    "packages": {
      "apt": [
        "graphviz"
      ],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  }
}'
```

```json
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "ready",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-25T08:40:17.904Z",
  "archived_at": null
}
```

### Errors

- 400 `invalid_request_error`: A field is not valid, or one is refused (`error_code` `validation_error`): `config.networking` is sent, `config.type` is not the computer's own, `config.packages` is sent for a Mac, or the labels would pass 16. `message` says which.
- 400 `invalid_request_error`: The computer is archived and takes no change (`error_code` `computer_archived`).
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 404 `not_found_error`: No computer in the key's workspace has this id (`Computer not found.`), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## Archive a computer

`POST /computers/{computer_id}/archive`

Archive a computer you no longer want to use. It takes no new work, and lists leave it out unless you ask for `include_archived=true`. It cannot be undone. Archiving a computer twice changes nothing. A computer with work still open on it cannot be archived.

The Linux computer is stopped and its disk is kept, and it frees the workspace's place for another. A Mac's access is taken away, so pairing it again makes a new Mac.

### Path parameters

- `computer_id` (computer id, required): The computer, such as `computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21`. A Mac has an id of the same form.

### Returns

The computer, with `archived_at` set. A Linux computer that was running is stopped as it is archived, so its `status` reads `stopped`, or `recovering` when Little Worker could not confirm that the machine stopped. One that was not running keeps its `status`. A Mac's `status` reads `revoked`.

### Example

```bash
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/archive" \
  -X POST \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
```

```json
{
  "type": "computer",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "scope": "organization",
  "name": "Workspace computer",
  "description": "Runs the shop's tasks.",
  "metadata": {
    "team": "ops"
  },
  "status": "stopped",
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allowed_hosts": [],
      "allow_mcp_servers": true,
      "allow_package_managers": true
    },
    "packages": {
      "type": "packages",
      "apt": [
        "graphviz"
      ],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": [
        "pandas==2.2.0"
      ]
    }
  },
  "created_at": "2026-10-20T09:14:02.331Z",
  "updated_at": "2026-10-25T17:12:04.126Z",
  "archived_at": "2026-10-25T17:12:03.418Z"
}
```

### Errors

- 400 `invalid_request_error`: `computer_id` is not a computer id. `error_code` is `validation_error`.
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 404 `not_found_error`: No computer in the key's workspace has this id (`Computer not found.`), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
- 409 `conflict_error`: A work record on the computer is not `stopped` yet, and a `stopping` one counts (`error_code` `computer_busy`). Stop that work with [Stop work on a computer](#stop-work-on-a-computer), then archive the computer.
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## Delete a computer

`DELETE /computers/{computer_id}`

Delete a computer for good. It does not need to be archived first. Its access is taken away, and a Linux computer's machine is ended and its place is free for another. Reads of it answer `404` afterwards. A computer with a work record on it, from any task, cannot be deleted, even after the task ends. Archive it instead.

### Path parameters

- `computer_id` (computer id, required): The computer, such as `computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21`. A Mac has an id of the same form.

### Returns

`type` is `computer_deleted`, with the computer's `id`.

### Example

```bash
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21" \
  -X DELETE \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
```

```json
{
  "type": "computer_deleted",
  "id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21"
}
```

### Errors

- 400 `invalid_request_error`: `computer_id` is not a computer id. `error_code` is `validation_error`.
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 404 `not_found_error`: No computer in the key's workspace has this id (`Computer not found.`), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
- 409 `conflict_error`: The computer has a work record, from any task and in any state (`error_code` `computer_busy`). Archive it instead.
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## List work on a computer

`GET /computers/{computer_id}/work`

List the work records of a computer, newest first by default. A record is one running stretch of one task on the computer, open or over. An archived computer lists its records too.

### Path parameters

- `computer_id` (computer id, required): The computer, such as `computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21`. A Mac has an id of the same form.

### Query parameters

- `limit` (integer): How many to answer, 1 to 1,000. The default is 20.
- `page` (string): The `next_page` of the answer before, to read the next page.
- `order` (string): `desc`, newest first (the default), or `asc`, oldest first. One of `desc`, `asc`.
- `created_at[gt]` (time): Only those made after this time, an RFC 3339 time compared to the millisecond the answer shows. `created_at[gte]`, `created_at[lt]` and `created_at[lte]` work the same way.

### Returns

A list: `data` holds the work records, as [Read a work record](#read-a-work-record) shows them, and `next_page` is the `page` to send for more (`null` on the last page).

### Example

```bash
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work?limit=20" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
```

```json
{
  "data": [
    {
      "type": "work",
      "id": "work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40",
      "computer_id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
      "data": {
        "type": "task",
        "id": "task_01JA8Z6Q4M3T9V2K7X5R1B0C8D"
      },
      "state": "active",
      "secret": null,
      "metadata": {
        "source": "crm"
      },
      "created_at": "2026-10-25T16:04:14.882Z",
      "acknowledged_at": "2026-10-25T16:04:15.140Z",
      "started_at": "2026-10-25T16:04:15.395Z",
      "latest_heartbeat_at": "2026-10-25T16:04:25.402Z",
      "stop_requested_at": null,
      "stopped_at": null
    }
  ],
  "next_page": null
}
```

### Errors

- 400 `invalid_request_error`: A filter is not valid, such as a `limit` outside 1 to 1,000, or `computer_id` is not a computer id (`error_code` `validation_error`). `page` is not a page this list gave with the same `order` and `created_at` filters (`error_code` `invalid_cursor`). Read the first page again.
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 404 `not_found_error`: No computer in the key's workspace has this id (`Computer not found.`), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## Read the work queue

`GET /computers/{computer_id}/work/stats`

Count the work that waits on a computer, and say whether its runner is listening for it. A runner is the program on the computer that takes a worker's calls. This works on an archived computer too.

### Path parameters

- `computer_id` (computer id, required): The computer, such as `computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21`. A Mac has an id of the same form.

### Returns

`type` is `work_queue_stats`, with these fields.

- `type` (string): Always `work_queue_stats`.
- `depth` (integer): How many records are `queued`: no runner has taken a call yet.
- `pending` (integer): How many records are `starting`: a runner took a call that is not running yet.
- `oldest_queued_at` (time, or null): When the oldest `queued` or `starting` record opened. `null` when none waits.
- `runners_polling` (integer): `1` when the computer's runner has been in touch in the last 30 seconds, and `0` when it has not. A computer has one runner.

### Example

```bash
curl https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work/stats \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
```

```json
{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "runners_polling": 1
}
```

### Errors

- 400 `invalid_request_error`: `computer_id` is not a computer id. `error_code` is `validation_error`.
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 404 `not_found_error`: No computer in the key's workspace has this id (`Computer not found.`), or it was deleted. On a shared workspace, a Mac that another person paired is not found either.
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## Read a work record

`GET /computers/{computer_id}/work/{work_id}`

Read one work record. A record opens at a task's first call on the computer. It is `stopped` once the task's run has ended, or a stop was asked for, and none of its calls is open. It reports what ran. The calls under it are what the computer runs.

### Path parameters

- `computer_id` (computer id, required): The computer, such as `computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21`. A Mac has an id of the same form.
- `work_id` (work id, required): The work record, such as `work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40`.

### Returns

`type` is `work`, with these fields.

- `type` (string): Always `work`.
- `id` (work id): The record's id: `work_` and 32 hex digits.
- `computer_id` (computer id): The computer the work is on.
- `data` (object): The task the work is for.
  - `type` (string): Always `task`.
  - `id` (task id): The task.
- `state` (string): Where the work is. `queued` waits for the computer, `starting` was taken by the computer, `active` has had a call start running, `stopping` was told to stop and waits for its open calls to end, and `stopped` is over. A record only moves forward. One of `queued`, `starting`, `active`, `stopping`, `stopped`.
- `secret` (string, or null): Always `null`. The computer's own runner holds a secret; no route here answers one.
- `metadata` (object): Your own labels for the record. It starts with the task's labels. Up to 16 keys of 1 to 64 characters, each with a string value of up to 512.
- `created_at` (time): When the record opened: at the task's first call on the computer.
- `acknowledged_at` (time, or null): When the computer took the first call (`starting`). `null` until then. Each step sets its time once.
- `started_at` (time, or null): When the first call started running (`active`). `null` until then.
- `latest_heartbeat_at` (time, or null): When the computer last reported that it was still on the work. `null` until it does.
- `stop_requested_at` (time, or null): When a stop was asked for (`stopping`). `null` until then.
- `stopped_at` (time, or null): When the work was over (`stopped`). `null` while it is not.

### Example

```bash
curl https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work/work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40 \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"
```

```json
{
  "type": "work",
  "id": "work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40",
  "computer_id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "data": {
    "type": "task",
    "id": "task_01JA8Z6Q4M3T9V2K7X5R1B0C8D"
  },
  "state": "active",
  "secret": null,
  "metadata": {
    "source": "crm"
  },
  "created_at": "2026-10-25T16:04:14.882Z",
  "acknowledged_at": "2026-10-25T16:04:15.140Z",
  "started_at": "2026-10-25T16:04:15.395Z",
  "latest_heartbeat_at": "2026-10-25T16:04:25.402Z",
  "stop_requested_at": null,
  "stopped_at": null
}
```

### Errors

- 400 `invalid_request_error`: `computer_id` or `work_id` is not an id of its kind. `error_code` is `validation_error`.
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 404 `not_found_error`: The computer has no record with this id (`Work not found.`), or the computer is not found (`Computer not found.`), for the reasons under [Read a computer](#read-a-computer).
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## Change a work record

`POST /computers/{computer_id}/work/{work_id}`

Change a work record's labels. A key with a string is set, a key set to `null` is removed, and keys left out stay. Without `metadata`, nothing changes.

### Path parameters

- `computer_id` (computer id, required): The computer, such as `computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21`. A Mac has an id of the same form.
- `work_id` (work id, required): The work record, such as `work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40`.

### Body

- `metadata` (object): Labels to set, up to 16 keys of 1 to 64 characters, each with a string value of up to 512 or `null`. A key set to `null` is removed. The record may not hold more than 16 keys after the change.

### Returns

The work record, as [Read a work record](#read-a-work-record) shows it.

### Example

```bash
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work/work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19" \
  -H "content-type: application/json" \
  -d '{
  "metadata": {
    "source": "crm"
  }
}'
```

```json
{
  "type": "work",
  "id": "work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40",
  "computer_id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "data": {
    "type": "task",
    "id": "task_01JA8Z6Q4M3T9V2K7X5R1B0C8D"
  },
  "state": "active",
  "secret": null,
  "metadata": {
    "source": "crm"
  },
  "created_at": "2026-10-25T16:04:14.882Z",
  "acknowledged_at": "2026-10-25T16:04:15.140Z",
  "started_at": "2026-10-25T16:04:15.395Z",
  "latest_heartbeat_at": "2026-10-25T16:04:25.402Z",
  "stop_requested_at": null,
  "stopped_at": null
}
```

### Errors

- 400 `invalid_request_error`: A field is not valid, such as a `metadata` that would hold more than 16 keys, or an id is not of its kind (`error_code` `validation_error`).
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 404 `not_found_error`: The computer has no record with this id (`Work not found.`), or the computer is not found (`Computer not found.`), for the reasons under [Read a computer](#read-a-computer).
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.

## Stop work on a computer

`POST /computers/{computer_id}/work/{work_id}/stop`

Stop the task that a work record is for. The task's run is asked to stop, on every computer it uses. Other tasks on the computer keep running. Stopping a record that is `stopped` answers it as it is.

By default the calls the computer already took finish, and the record reads `stopping` until they report. With `force`, every open call ends now: one the computer had not taken is `cancelled`, and one it had taken is `outcome_unknown`, because nobody can say what it did. The answer reads `stopped`. A taken call whose outcome is unknown holds the Linux computer for review.

### Path parameters

- `computer_id` (computer id, required): The computer, such as `computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21`. A Mac has an id of the same form.
- `work_id` (work id, required): The work record, such as `work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40`.

### Body

- `force` (boolean): `true` ends every open call now. Left out or `false`, calls the computer already took finish first. Send `{}` for the gentle stop.

### Returns

The work record, as [Read a work record](#read-a-work-record) shows it. Its `state` is `stopping` after a gentle stop with calls still open, and `stopped` after a forced stop or when no call was open.

### Example

```bash
curl "https://core.thelittleworker.com/api/v1/computers/computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21/work/work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40/stop" \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19" \
  -H "content-type: application/json" \
  -d '{}'
```

```json
{
  "type": "work",
  "id": "work_a41d7c0e2b9f4e6a8c3d5b7f9e1a2c40",
  "computer_id": "computer_5e3c9a1f7b2d4c8e9a0f1b3d5c7e9a21",
  "data": {
    "type": "task",
    "id": "task_01JA8Z6Q4M3T9V2K7X5R1B0C8D"
  },
  "state": "stopping",
  "secret": null,
  "metadata": {
    "source": "crm"
  },
  "created_at": "2026-10-25T16:04:14.882Z",
  "acknowledged_at": "2026-10-25T16:04:15.140Z",
  "started_at": "2026-10-25T16:04:15.395Z",
  "latest_heartbeat_at": "2026-10-25T16:04:25.402Z",
  "stop_requested_at": "2026-10-25T16:09:41.226Z",
  "stopped_at": null
}
```

### Errors

- 400 `invalid_request_error`: An id is not of its kind, `force` is not `true` or `false`, or the body holds another field (`error_code` `validation_error`).
- 401 `authentication_error`: The key is missing, removed, or not a key. Send it in `x-api-key`.
- 404 `not_found_error`: The computer has no record with this id (`Work not found.`), or the computer is not found (`Computer not found.`), for the reasons under [Read a computer](#read-a-computer).
- 429 `rate_limit_error`: The workspace made too many requests this minute. Wait the seconds in `Retry-After`, then try again.