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

# List GPU Nodes

> Retrieve all GPU nodes registered in Aria Compute PIN, including SSH access details, labels, status, and agent counts.

Use this endpoint to list every GPU node in your Aria Compute PIN cluster. Each node entry includes connection details, labels, current status, and the number of deployed agents.

## Endpoint

**GET** `/v1/gpu-nodes`

Authorization: Bearer API key required.

## Response

<ResponseField name="items" type="array" required>
  List of GPU node objects.

  <Expandable>
    <ResponseField name="id" type="string" required>
      Node identifier, e.g. gn\_abc123de.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Human-readable node name.
    </ResponseField>

    <ResponseField name="ip" type="string" required>
      Node IP address used for SSH.
    </ResponseField>

    <ResponseField name="ssh_port" type="integer">
      SSH port (defaults to 22).
    </ResponseField>

    <ResponseField name="ssh_user" type="string" required>
      SSH username.
    </ResponseField>

    <ResponseField name="spec" type="string">
      Hardware or configuration spec summary.
    </ResponseField>

    <ResponseField name="labels" type="array of strings">
      Scheduling labels.
    </ResponseField>

    <ResponseField name="status" type="string">
      Node status, e.g. active.
    </ResponseField>

    <ResponseField name="agent_count" type="integer">
      Number of agents deployed on this node.
    </ResponseField>

    <ResponseField name="created_at" type="string (ISO 8601)">
      Creation timestamp.
    </ResponseField>

    <ResponseField name="updated_at" type="string (ISO 8601)">
      Last update timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

```bash theme={null}
curl -s http://<pin-host>:8001/v1/gpu-nodes \
  -H "Authorization: Bearer $ARIA_PIN_KEY"
```

```json theme={null}
{
  "items": [
    {
      "id": "gn_a1b2c3d4",
      "name": "node-01",
      "ip": "10.0.1.10",
      "ssh_port": 22,
      "ssh_user": "ubuntu",
      "spec": "A100-80G x8",
      "labels": ["training", "a100"],
      "status": "active",
      "agent_count": 2,
      "created_at": "2024-05-01T12:00:00Z",
      "updated_at": "2024-05-10T08:30:00Z"
    }
  ]
}
```


## Related topics

- [List and Deploy Node Agents](/api-reference/pin/gpu-nodes/agents.md)
- [Delete a GPU Node](/api-reference/pin/gpu-nodes/delete.md)
- [Create a GPU Node](/api-reference/pin/gpu-nodes/create.md)
- [Get a GPU Node](/api-reference/pin/gpu-nodes/get.md)
- [Update a GPU Node](/api-reference/pin/gpu-nodes/update.md)