---
title: "One node: state, rate, queue position"
method: GET
path: "/preview/nodes/{name}"
tags: ["nodes"]
---

# One node: state, rate, queue position

`GET /preview/nodes/{name}`

## Request

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

Show one node by name: status, image, the effective rate, its region, and, while queued or provisioning, the queue position and wait estimates (estimated_wait_seconds; estimated_ready_seconds and its p90; pace polling off the p90; null = no history; your place is held). Poll until running, then run_command; while queued, `arrival_note` says what to do now. While placed, `resources` is the container's cgroup budget (cpu_limit, memory_limit_bytes) - size work to those, not to os.cpu_count()/free, which report the HOST - and `environment` the CUDA-compile facts (image_nvcc, image_torch, driver_version, cuda_major_max, compute_capability, gpu_graphics, gpu_graphics_enabled: GPU graphics is off by default, on per organization on request via file_ticket) - node_doctor checks the pairing. `gpu_memory` is per-GPU used/free VRAM: read free_mib_min before co-locating work. A network member shows `network` (dns_name, region/zone, data_plane: up, converging, not_placed, or unavailable). A ready node with no session reports "running (idle)" plus idle_stops_at - when it auto-stops unless a run_command lands first; hold_node keeps it awake (shown as `hold`). A silent host (execs failing "host isn't responding") shows as `host` {responding: false, silent_seconds}; absent = it answers. Status checks never wake a stopped node. A stopped node carries `stopped` {reason, at, note, ran_seconds (billed length)} plus wake_estimate (null if it cannot start): what a wake now would be quoted (queued_wakes, ready estimates; a reading, not a reservation; assumes_contested prices contention). durable_as_of is the newest instant of the disk replicated off its machine (storage tier: docs). A retiring machine shows machine_retires_at and machine_retirement_note about 45 minutes ahead, for a parked disk too; poll for it on long runs. A failed create answers status "failed" with the real error for an hour; re-creating the name starts fresh. A shell can poll GET /preview/nodes/{name} (docs, HTTP API).

## Path parameters

- `name` string, required: Node name (from `list_nodes`).

## Query parameters

- `workspace` string

## Request body

- object
  - `mission` string, nullable: The mission you are working under (from open_mission): the answer gains `same_mission`, the only signal that separates this agent from your OTHER agents, which share your account.

## Response `200`

The capability's JSON result.

- Result: The capability's result: the same object the MCP tool returns as structuredContent. Resources carry an `object` type discriminator and an immutable id; money is integer micro-dollars in `*_usd_micros` fields.
  - `object` string: The resource type, when the result is one resource.

## 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)