> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simular.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Machines

> GET /v1/agents/machines

Lists the computers on your account.

## Request

```bash theme={null}
curl -s "$SAI_API_URL/v1/agents/machines" \
  -H "Authorization: Bearer $SAI_API_KEY"
```

## Response

```json theme={null}
{
  "machines": [
    {
      "machineId": "m_9c1e",
      "name": "Sai cloud computer",
      "updatedAt": 1789990000000,
      "status": "hibernated",
      "canWake": true,
      "kind": "cloud",
      "online": true
    },
    {
      "machineId": "m_7f2a",
      "name": "Work Desktop",
      "updatedAt": 1790000000000,
      "status": "active",
      "canWake": false,
      "kind": "own",
      "online": true
    }
  ]
}
```

| Field | Notes |
| - | - |
| `machineId` | Pass as `machineId` on other calls. |
| `name` | The name shown in the Sai app. Absent when the computer has none. |
| `updatedAt` | Unix time in milliseconds of the last status update. |
| `status` | The raw machine status string. Absent when unknown. Prefer `online`. |
| `canWake` | Whether `POST /wake` applies to this computer. |
| `kind` | `cloud` (hosted by Simular) or `own` (your desktop app). |
| `online` | `true` when the computer is `active`, `hibernated` (a message wakes it), or its agent reports online. |

Rows are sorted by name.

## Free accounts

A free account whose computer is not claimed right now sees one synthetic row:

```json theme={null}
{
  "machines": [
    {
      "machineId": "free-3fA9kQ2xYz",
      "name": "Sai cloud computer (free)",
      "updatedAt": 0,
      "canWake": false,
      "kind": "cloud",
      "online": false
    }
  ]
}
```

`online: false` means the first message will claim and start the computer, which takes about two minutes. While it is claimed, the row is a normal one with the same `machineId`.

<Note>
  `kind`, `online` and the free-account row are available from October 1.
</Note>

## Create a computer

```
POST /v1/agents/machines
```

Creates a Windows cloud computer for a paid account. It needs a signed-in session: the portal's **Create a cloud computer** button in the [Playground](https://platform.simular.ai/playground) calls it. An API key cannot create a computer, because a computer costs money and is created with the account owner's own checks (plan, payment method, quota, one creation at a time).

Body (optional):

```json theme={null}
{ "name": "Work PC" }
```

Response `202`:

```json theme={null}
{ "taskId": "3f1c…", "message": "Creating your computer. It appears in GET /v1/agents/machines within a few minutes." }
```

Poll `GET /v1/agents/machines` until the new computer is listed with `online: true`, usually within a few minutes.

| Status | `error` | When |
| - | - | - |
| `403` | `session_required` | Called with an API key. The body carries `createUrl`, the portal page to send the user to. |
| `409` | `free_plan_computer` | Free plan. Its computer is the pooled one, started by the first task. |
| `429` | `busy`, or a rate-limit message | A creation is already in progress, or more than 3 in an hour. |
| `403` | `not_billable` | The account cannot pay for a computer right now. |