---
title: "List all saved machines with access and live status"
method: GET
path: "/api/v1/status"
---

# List all saved machines with access and live status

`GET /api/v1/status`

## Request

- Base URL: `https://aicommander.dev`
- URL: `https://aicommander.dev/api/v1/status`
- Auth: HTTP bearer

Returns every machine saved to the API-key account. `blocked` means operator approval/block state; `planRestricted` means the account plan does not currently allow that record, and the two booleans are independent. Free keeps all records but only the 10 oldest by created_at then id are usable; deleting an older one promotes the next oldest. Pro can use all saved records up to the technical 100-record ceiling. A plan-restricted entry is deliberately not probed and carries `online:false`, `lastSeenAt:null`, with platform, agentVersion and GPU telemetry omitted. Do not interpret that suppression as proof the machine itself is offline; attempts to use it fail 403 with `reason: plan_device_limit`. Requires an account API key; anonymous callers get 403 and can query only one AIC- code via /api/v1/status/{code}.

## Response `200`

The account's machines.

- object
  - `ok` true, required
  - `machines` object[], required
    - `alias` string, required: The saved name for the machine — pass it as `code` to the other endpoints.
    - `online` boolean, required: True when the agent is connected now. Always false when planRestricted is true because liveness is intentionally not queried.
    - `lastSeenAt` string, nullable, required: ISO timestamp of the last frame the relay heard FROM THE AGENT — the machine's own heartbeat. It is NOT stamped by your queries: it used to report the last authorized call, so a machine that had been dead for days could read 'seen a minute ago' simply because you had just asked about it. `null` means UNKNOWN (the relay has never heard from this agent, or the link is blocked) and is never back-filled — do not read null as recent.
    - `hostname` string: The machine's OWN name, as its agent reported it — WHICH PHYSICAL BOX this record is. The alias beside it is only what the account typed when saving the machine, so an account holding aic-wfs-pc, aic-wfs-pc2 and aic-wfs-pc3 cannot tell them apart without this. While `online` is false it is the last known value, and it is omitted for a machine that never registered and for blocked links, like lastSeenAt.
    - `localIps` string[]: The machine's own local IP addresses (non-loopback, non-link-local), as its agent last reported them — the other half of 'which box is this?', and usually the half a human recognizes on their own network. These are addresses on the MACHINE's side of its NAT: a label for telling machines apart, never a route — nothing can connect to them, and every command goes through the relay regardless. Absent means the machine's agent did not report any (an agent too old to send them, or none it was confident about) and NEVER that the machine has no network; omitted for blocked links. While `online` is false these are last known and DHCP may since have handed one of them to a different machine. At most 8 entries.
    - `platform` string: The agent's OS — 'darwin', 'linux' or 'win32'. THIS IS HOW YOU PICK THE SHELL DIALECT before writing a command ('win32' means cmd.exe, not /bin/sh), without a per-machine GET /api/v1/status/{code}. While `online` is false this is the LAST KNOWN value from the agent's final registration, not current state. Omitted for blocked links, like lastSeenAt.
    - `agentVersion` string: The agent build the machine last registered with; last-known while offline, and omitted for blocked links. This is the build that actually RUNS your commands — see installedVersion.
    - `installedVersion` string: The agent build sitting on the machine's DISK. Present ONLY when it differs from `agentVersion`, which means an update was installed but the app was never restarted, so the old process is still the one serving this relay: `agentVersion` is what executes your commands, and nothing added or fixed in `installedVersion` applies to this machine yet. Absent is the healthy case and carries no information — the two agree, the agent is too old to report the on-disk build, or it could not determine one. Never present for an offline machine (there is no running process to be stale) or for blocked links. The machine is NOT offline or broken while this is set; the remedy is quitting and reopening the AI Commander app on it, or rebooting it.
    - `blocked` boolean, required: True when the link is awaiting the operator's approval and cannot yet be used.
    - `planRestricted` boolean, required: True when this saved record is outside the current account plan. Independent of blocked. On Free, only the 10 oldest records by created_at then id are usable; newer records remain saved and become usable after deleting an older record or upgrading. Restricted records expose no liveness/platform/GPU telemetry and operations fail with reason plan_device_limit.
    - `deviceLinked` boolean, required: False for a legacy link with no device binding (alias can't be resolved).
    - `gpus` GpuDevice[]: The machine's NVIDIA devices, as last reported. THIS IS HOW YOU PICK A MACHINE FOR COMPUTE WORK: prefer an online machine with a card that has enough free VRAM (total − used) and low utilization, then pass that card's `index` as `gpu_index` to POST /api/v1/jobs. Omitted entirely when the machine reported no NVIDIA card (or has no driver) and for blocked links, exactly like lastSeenAt. While `online` is false these are the last known figures and may be stale.
      - `index` integer, required: nvidia-smi device index — also the value to pass as `gpu_index` when starting a job.
      - `name` string, required: Marketing name, e.g. 'NVIDIA GeForce RTX 5080'.
      - `memoryTotalMiB` integer, required
      - `memoryUsedMiB` integer, required: Free VRAM is memoryTotalMiB − memoryUsedMiB.
      - `utilizationPct` integer, required
      - `driverVersion` string: Present when nvidia-smi reported one.
    - `elevatedCapable` boolean: Present and `true` only when this machine can run an `elevated: true` command RIGHT NOW — its connected agent has a privileged helper installed, registered and answering. THIS IS HOW YOU PICK A TARGET FOR PRIVILEGED WORK without a per-machine GET /api/v1/status/{code}. It is never emitted as `false`: absence means 'not capable, or not reported', which covers a machine with no helper, an agent too old to say, and an offline machine. Like lastSeenAt it describes the live connection, so the relay drops it when that connection ends, and it is omitted for blocked links. See elevatedUnavailableReason for why a machine is not capable.
    - `elevatedUnavailableReason` 'platform_unsupported' | 'not_installed' | 'not_registered' | 'endpoint_unreachable' | 'protocol_mismatch' | 'endpoint_conflict': WHY the machine cannot run elevated commands, when its agent said so — the fact that used to be invisible, because the capability flag (`elevatedCapable` on a machine-list row, `elevatedExec` inside `agentInfo`) is only ever emitted when true. Only present alongside an ABSENT capability flag, and only for an online, non-blocked machine — it describes a live connection, so an offline row carries neither field; absent means the agent did not report a reason (too old, offline, or a probe that concluded nothing), in which case say nothing rather than guess. `platform_unsupported`: Linux, where there is no privileged helper BY DESIGN — the remedy is to stop passing `elevated`, not to install anything. `not_installed`: the helper's files are not on the machine; reinstall AI Commander. `not_registered`: the files are there but the OS was never told to run them (no SYSTEM scheduled task on Windows, no LaunchDaemon on macOS) — a healthy-looking install can simply have no helper, and reinstalling registers it. `endpoint_unreachable`: the helper's files are installed, but nothing answered its local endpoint. Whether the operating system was ever told to run it is NOT established — the agent reports this reason both for a registered helper that is simply not running AND for a machine where that registration query could not be answered — so do not tell a user their helper is registered. It normally starts at boot, so a reboot is the cheapest thing to try; if it still does not answer, the machine's own diagnostics say which precondition failed, including whether it is registered at all. `protocol_mismatch`: it answered speaking an IPC protocol version this agent will not speak — half of a paired upgrade landed; finish the upgrade. `endpoint_conflict`: two endpoints answered with different identities, so the agent refuses all of them — something that is not the helper is listening. Purely diagnostic: nothing becomes permitted because this field is present or absent, and elevated work is still refused unless the live agent advertises the capability. It deliberately carries no paths, ports or signer subjects — for those, run the diagnostics ON the machine (desktop tray → 'Run Diagnostics…', or `aicommander-agent doctor` on a headless install).
    - `runningJobs` integer: Detached jobs running on the machine RIGHT NOW, as its agent last pushed them (no extra call to the machine). Present only for an online, non-blocked, non-plan-restricted machine whose agent reports it. Absent means UNKNOWN — an offline machine, or an agent too old to report the count — never 0.

## Other responses

- `401`: A token was supplied but is not a valid API key/admin/OAuth token.
- `403`: Resolved but refused. Causes include expired anonymous access; Free/anonymous file transfer; `reason: plan_device_limit`; independent operator block/approval; or `error: reactivation_required`. For plan_device_limit, delete an older saved machine to promote the next or upgrade to Pro. For file transfer, use Pro. Do not conflate either with operator approval.
- `429`: Per-IP or global tool-call rate limit exceeded.

---

[API](https://skmtc.dev/aicommander/apis/ai-commander-remote-shell-and-long-running-jobs-api.md) · [All operations](https://skmtc.dev/aicommander/apis/ai-commander-remote-shell-and-long-running-jobs-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aicommander/apis/ai-commander-remote-shell-and-long-running-jobs-api/revisions/a6bb89f779a1?raw)