---
title: "List nodes (paged)"
method: GET
path: "/preview/nodes"
tags: ["nodes"]
---

# List nodes (paged)

`GET /preview/nodes`

## Request

- Base URL: `https://autoresearch.sfcompute.com`
- URL: `https://autoresearch.sfcompute.com/preview/nodes`
- Auth: HTTP bearer

List the nodes in your workspace (GPU and CPU shapes): name, chip, state, and - while placed on a region-labeled machine - the region it runs in (absent = not placed or not reported; CPU nodes may run far from your GPU nodes, so check it before assuming a LAN). A private-network member also shows its network with stable mesh addresses, DNS name, region/zone, and data_plane (up, converging, not_placed, or unavailable; attach_network explains each). Work on a node with run_command; poll a pending node with get_node. THESE ARE NOT ALL YOUR NODES: a workspace is shared, and other agents in other sessions - plus every human member - create nodes here too. Each row carries `yours`, `created_by`, and the `mission` it was created for, plus `sessions` and `running_commands` when work is live on it; a `shared` block counts what is not yours. PASS mission: "<what you are working on>": `yours` is an ACCOUNT fact, and the several agents one person runs at once share that account, so without it a node from your own other investigation reads as yours. With it, every row gains `same_mission` - work only where that is true. Create your own node rather than borrowing one: reusing a node overwrites its files and environment, and stopping or deleting it destroys work you did not start. A node whose state reads "stopped (no restorable disk copy)" cannot start, because the platform has no copy of its disk that it can restore. The platform refuses every wake of it, and get_node's stopped.note says why.

## Query parameters

- `cursor` string: Opaque page cursor: the `next_cursor` a previous response returned. Omit for the first page.
- `limit` integer: Rows per page. Clamped to the range shown.
- `mission` string, nullable: The mission you are working under (from open_mission). Naming it marks each row with `same_mission`, and is the only way to tell your own OTHER agents' nodes from this one's: a request resolves to your ACCOUNT, and parallel agents on one login share it.
- `workspace` string

## Response `200`

The capability's JSON result.

- List: The list envelope every paging endpoint returns.
  - `items` Result[], required
    - `object` string: The resource type, when the result is one resource.
  - `next_cursor` string: Pass as ?cursor= for the next page. Absent on the last page. Opaque: never parse it.
  - `object` 'list', required

## Other responses

- `400`: Malformed request: bad JSON, a parameter that does not parse, or a value outside its range. Code `invalid`.
- `401`: No bearer token, or one this API cannot verify. Code `unauthenticated`.
- `403`: Authenticated, but the token's scopes or the account's role do not reach this operation. The message names the scope word to request. Code `forbidden`.
- `404`: No such route. Code `not_found`; the body names the OpenAPI document.
- `422`: A well-formed request the platform declined: no such node, a cap reached, a state that forbids the move. The message says which, and what to do instead. Code `refused`.
- `429`: Over this door's per-customer budget. Wait `Retry-After` seconds. Code `rate_limited`.
- `500`: Our fault. Retry; if it persists, quote the request-id. Code `internal`.

---

[API](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api.md) · [All operations](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/revisions/f88dcb70ac6c?raw)