> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/fleet-intel/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/fleet-intel/_mcp/server.

# Get nodes overview and states

GET /v1/nodes

Get list of nodes with current state and overview. Use view=detail (default) for full response or view=basic for a lightweight nodeUUID + hostname list (see models.BasicNodesResponse). All filter parameters are optional arrays - empty means no filter applied.

Reference: https://docs.nvidia.com/fleet-intel/fleet-intel/api-explorer/nodes/get-v-1-nodes

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: fleet-intelligence
  version: 1.0.0
paths:
  /v1/nodes:
    get:
      operationId: getV1Nodes
      summary: Get nodes overview and states
      description: >-
        Get list of nodes with current state and overview. Use view=detail
        (default) for full response or view=basic for a lightweight nodeUUID +
        hostname list (see models.BasicNodesResponse). All filter parameters are
        optional arrays - empty means no filter applied.
      tags:
        - nodes
      parameters:
        - name: view
          in: query
          description: >-
            View mode: 'detail' for full response (default) or 'basic' for
            nodeUUID + hostname only (lightweight query, does not support
            filtering or sorting by healthStatuses, integrityChecks,
            firmwareChecks, or agentStatuses).
          required: false
          schema:
            $ref: '#/components/schemas/V1NodesGetParametersView'
            default: detail
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            default: 0
        - name: pageSize
          in: query
          description: Page size
          required: false
          schema:
            type: integer
            default: 10
        - name: nodeUUIDs
          in: query
          description: Filter by specific node UUIDs. Empty means all nodes
          required: false
          schema:
            type: array
            items:
              type: string
        - name: healthStatuses
          in: query
          description: Filter by health status values
          required: false
          schema:
            type: array
            items:
              $ref: >-
                #/components/schemas/V1NodesGetParametersHealthStatusesSchemaItems
        - name: computeZoneIds
          in: query
          description: Filter by computezone IDs. Empty means all computezones
          required: false
          schema:
            type: array
            items:
              type: string
        - name: computeZoneNames
          in: query
          description: >-
            Filter by computezone names (partial match). Empty means all
            computezones
          required: false
          schema:
            type: array
            items:
              type: string
        - name: nodeGroupIds
          in: query
          description: Filter by nodegroup IDs. Empty means all nodegroups
          required: false
          schema:
            type: array
            items:
              type: string
        - name: nodeGroupNames
          in: query
          description: >-
            Filter by nodegroup names (partial match). Empty means all
            nodegroups
          required: false
          schema:
            type: array
            items:
              type: string
        - name: gpuTypes
          in: query
          description: Filter by GPU type values. Empty means all GPU types
          required: false
          schema:
            type: array
            items:
              type: string
        - name: gpuCounts
          in: query
          description: Filter by GPU count values. Empty means all GPU counts
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: publicIPs
          in: query
          description: Filter by public IP addresses. Empty means all public IPs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: privateIPs
          in: query
          description: Filter by private IP addresses. Empty means all private IPs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: integrityChecks
          in: query
          description: Filter by integrity check status
          required: false
          schema:
            type: array
            items:
              $ref: >-
                #/components/schemas/V1NodesGetParametersIntegrityChecksSchemaItems
        - name: firmwareChecks
          in: query
          description: Filter by firmware check status
          required: false
          schema:
            type: array
            items:
              $ref: >-
                #/components/schemas/V1NodesGetParametersFirmwareChecksSchemaItems
        - name: agentStatuses
          in: query
          description: Filter by agent status values
          required: false
          schema:
            type: array
            items:
              $ref: >-
                #/components/schemas/V1NodesGetParametersAgentStatusesSchemaItems
        - name: hostname
          in: query
          description: Filter by hostname (case-insensitive partial match)
          required: false
          schema:
            type: string
        - name: sortBy
          in: query
          description: >-
            Field to sort by. gpuFirmwareVersions pins nodes whose GPUs have
            mismatched vbios versions to the top, then sorts the remaining
            (uniform) nodes by that common vbios in the requested order.
          required: false
          schema:
            $ref: '#/components/schemas/V1NodesGetParametersSortBy'
            default: hostname
        - name: order
          in: query
          description: Sort order (asc, desc)
          required: false
          schema:
            $ref: '#/components/schemas/V1NodesGetParametersOrder'
            default: asc
      responses:
        '200':
          description: Basic view response (view=basic)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/nodes_getV1Nodes_Response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '403':
          description: Forbidden - UAM authorization denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '499':
          description: Client Closed Request - request was canceled by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
components:
  schemas:
    V1NodesGetParametersView:
      type: string
      enum:
        - detail
        - basic
      default: detail
      title: V1NodesGetParametersView
    V1NodesGetParametersHealthStatusesSchemaItems:
      type: string
      enum:
        - Healthy
        - Degraded
        - Unhealthy
        - Unknown
      title: V1NodesGetParametersHealthStatusesSchemaItems
    V1NodesGetParametersIntegrityChecksSchemaItems:
      type: string
      enum:
        - Verified
        - Unverified
        - Degraded
        - Pending
        - Unsupported
        - Unknown
      title: V1NodesGetParametersIntegrityChecksSchemaItems
    V1NodesGetParametersFirmwareChecksSchemaItems:
      type: string
      enum:
        - Passed
        - Failed
        - Unknown
      title: V1NodesGetParametersFirmwareChecksSchemaItems
    V1NodesGetParametersAgentStatusesSchemaItems:
      type: string
      enum:
        - Online
        - Offline
        - Unknown
      title: V1NodesGetParametersAgentStatusesSchemaItems
    V1NodesGetParametersSortBy:
      type: string
      enum:
        - hostname
        - nodeUUID
        - healthStatus
        - nodegroup
        - computezone
        - gpuType
        - gpuCount
        - integrityCheck
        - agentStatus
        - agentVersion
        - kernelVersion
        - gpuDriverVersion
        - gpuFirmwareVersions
      default: hostname
      title: V1NodesGetParametersSortBy
    V1NodesGetParametersOrder:
      type: string
      enum:
        - asc
        - desc
      default: asc
      title: V1NodesGetParametersOrder
    models.AgentStatus:
      type: string
      enum:
        - Online
        - Offline
        - Unknown
      title: models.AgentStatus
    models.FirmwareCheck:
      type: string
      enum:
        - Passed
        - Failed
        - Unknown
      title: models.FirmwareCheck
    models.GPUFirmwareVersion:
      type: object
      properties:
        firmwareVersion:
          type: string
        gpuIndex:
          type: string
      title: models.GPUFirmwareVersion
    models.HealthState:
      type: string
      enum:
        - Healthy
        - Degraded
        - Unhealthy
        - Unknown
        - Unsupported
        - Pending
      title: models.HealthState
    models.IntegrityCheck:
      type: string
      enum:
        - Verified
        - Unverified
        - Degraded
        - Pending
        - Unsupported
        - Unknown
      title: models.IntegrityCheck
    models.NRASErrorDetail:
      type: object
      properties:
        code:
          type: integer
        description:
          type: string
        fieldName:
          type: string
        httpStatus:
          type: string
        message:
          type: string
      title: models.NRASErrorDetail
    models.CertChainStatus:
      type: object
      properties:
        x-nvidia-cert-expiration-date:
          type: string
        x-nvidia-cert-ocsp-nonce-matches:
          type: boolean
        x-nvidia-cert-ocsp-response-valid:
          type: boolean
        x-nvidia-cert-ocsp-status:
          type: string
        x-nvidia-cert-revocation-reason:
          type: string
        x-nvidia-cert-status:
          type: string
      title: models.CertChainStatus
    models.JWTClaims:
      type: object
      properties:
        eat_nonce:
          type: string
        exp:
          type: integer
        hwmodel:
          type: string
          description: Hardware info
        iat:
          type: integer
        iss:
          type: string
          description: Standard JWT claims
        jti:
          type: string
        measres:
          type: string
        nbf:
          type: integer
        sub:
          type: string
        ueid:
          type: string
        x-nvidia-attestation-warning:
          type: string
        x-nvidia-error-details:
          type: array
          items:
            $ref: '#/components/schemas/models.NRASErrorDetail'
        x-nvidia-gpu-arch-check:
          type: boolean
          description: NVIDIA attestation claims - GPU specific
        x-nvidia-gpu-attestation-report-cert-chain:
          $ref: '#/components/schemas/models.CertChainStatus'
        x-nvidia-gpu-attestation-report-nonce-match:
          type: boolean
        x-nvidia-gpu-attestation-report-parsed:
          type: boolean
        x-nvidia-gpu-attestation-report-signature-verified:
          type: boolean
        x-nvidia-gpu-vbios-rim-fetched:
          type: boolean
        x-nvidia-gpu-vbios-rim-measurements-available:
          type: boolean
        x-nvidia-gpu-vbios-version:
          type: string
        x-nvidia-mismatch-measurement-records:
          type: array
          items:
            description: Any type
        x-nvidia-overall-att-result:
          type: boolean
          description: NVIDIA attestation claims - overall result (for overall JWT)
      title: models.JWTClaims
    models.IntegrityCheckExtraInfo:
      type: object
      properties:
        errorDetails:
          type: string
        gpuEvidencePresent:
          type: boolean
        gpuResults:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/models.JWTClaims'
        nrasCallResult:
          type: string
        overallAttestationResult:
          type: boolean
      title: models.IntegrityCheckExtraInfo
    models.Node:
      type: object
      properties:
        agentStatus:
          $ref: '#/components/schemas/models.AgentStatus'
        agentVersion:
          type: string
        computeZone:
          type: string
        firmwareCheck:
          $ref: '#/components/schemas/models.FirmwareCheck'
        gpuCount:
          type: integer
        gpuDriverVersion:
          type: string
        gpuFirmwareVersions:
          type: array
          items:
            $ref: '#/components/schemas/models.GPUFirmwareVersion'
        gpuType:
          type: string
        healthStatus:
          $ref: '#/components/schemas/models.HealthState'
        hostname:
          type: string
        integrityCheck:
          $ref: '#/components/schemas/models.IntegrityCheck'
        integrityCheckExtraInfo:
          $ref: '#/components/schemas/models.IntegrityCheckExtraInfo'
        integrityCheckReason:
          type: string
        kernelVersion:
          type: string
        lastIntegrityCheckTS:
          type: string
        lastUpdatedTS:
          type: string
        nodeGroup:
          type: string
        nodeUUID:
          type: string
        privateIP:
          type: string
        publicIP:
          type: string
      title: models.Node
    models.NodesResponse:
      type: object
      properties:
        hasMore:
          type: boolean
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/models.Node'
        page:
          type: integer
        pageSize:
          type: integer
        total:
          type: integer
      title: models.NodesResponse
    models.SimpleNode:
      type: object
      properties:
        hostname:
          type: string
        nodeUUID:
          type: string
      title: models.SimpleNode
    models.BasicNodesResponse:
      type: object
      properties:
        hasMore:
          type: boolean
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/models.SimpleNode'
        page:
          type: integer
        pageSize:
          type: integer
        total:
          type: integer
      title: models.BasicNodesResponse
    nodes_getV1Nodes_Response_200:
      oneOf:
        - $ref: '#/components/schemas/models.NodesResponse'
        - $ref: '#/components/schemas/models.BasicNodesResponse'
      title: nodes_getV1Nodes_Response_200
    models.KASRequestStatus:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID for tracing
        statusCode:
          type: string
          description: Status code from KAS
        statusDescription:
          type: string
          description: Status description from KAS
      description: >-
        RequestStatus contains KAS-specific error details

        This is added to reflect the field in OpenAPI docs for UI reference and
        not populated by our code

        If KAS returns an error, the request will not be forwarded to the
        backend
      title: models.KASRequestStatus
    models.ErrorResponse:
      type: object
      properties:
        details:
          type: string
          description: Detailed error information
        error:
          type: string
          description: Error message or type
        requestStatus:
          $ref: '#/components/schemas/models.KASRequestStatus'
      description: >-
        Standard error response returned by all API endpoints. For KAS API
        errors, requestStatus fields are populated.
      title: models.ErrorResponse

```

## Examples



**Response**

```json
{
  "hasMore": false,
  "nodes": [
    {
      "agentStatus": "Online",
      "agentVersion": "1.2.3",
      "computeZone": "compute-zone-1",
      "firmwareCheck": "Passed",
      "gpuCount": 4,
      "gpuDriverVersion": "550.120",
      "gpuFirmwareVersions": [
        {
          "firmwareVersion": "90.17.A9.00.0B",
          "gpuIndex": "0"
        }
      ],
      "gpuType": "NVIDIA-T400-4GB",
      "healthStatus": "Healthy",
      "hostname": "node-001",
      "integrityCheck": "Verified",
      "integrityCheckExtraInfo": {
        "errorDetails": "SDK error: code=13, message=nonce refresh failed",
        "gpuEvidencePresent": true,
        "gpuResults": {},
        "nrasCallResult": "NRAS attestation failed: GPU-0: NONCE_NOT_MATCHING",
        "overallAttestationResult": false
      },
      "integrityCheckReason": "Attestation verification unavailable: SDK error",
      "kernelVersion": "6.8.0-49-generic",
      "lastIntegrityCheckTS": "2024-01-15T10:30:00Z",
      "lastUpdatedTS": "2024-01-15T10:30:00Z",
      "nodeGroup": "node-group-1",
      "nodeUUID": "node-123",
      "privateIP": "10.0.0.100",
      "publicIP": "203.0.113.100"
    }
  ],
  "page": 0,
  "pageSize": 10,
  "total": 100
}
```

**SDK Code**

```python
import requests

url = "https://api.example.com/v1/nodes"

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'https://api.example.com/v1/nodes';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/nodes"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/nodes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.example.com/v1/nodes")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.example.com/v1/nodes');

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/v1/nodes");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v1/nodes")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```