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

# List advice

GET /v1/advice

Retrieve a list of advice for jobs. Advice includes only the desired state and node exclusions that the Advisor has computed for jobs. This is used by the NVIDIA Recovery Job Controller to synchronize job advice updates. Use the `page` parameter to get the next page of advice records.

Reference: https://docs.nvidia.com/recovery/gateway-reference/heimdall-service/listadvice

## Request

### Query parameters

- `page` (string, optional) — The opaque page token from the previous response's next_page_token field.
- `limit` (integer, optional) — The maximum number of advice records to return. Defaults to 100 and cannot exceed 250.
- `onlyActive` (boolean, optional) — Return only Advice that can still require reconciliation.

## Response

### 200

A successful response.

- `advice` (list of v1Advice, optional) — The list of advice records.
- `count` (integer, optional) — The total count of advice records returned.
- `nextPageToken` (string, optional) — The opaque token to use for the next page of results.

## Types

### v1Advice

Advice represents advice computed by the Advisor for a job. This includes desired state, node constraints, and detected issues.

- `heimdallJobId` (string, optional) — The UUID assigned by NVIDIA Recovery.
- `jobId` (string, optional) — Scheduler-specific job identifier.
- `schedulerMetadata` (V1AdviceSchedulerMetadata, optional) — Scheduler metadata that is specific to the scheduler such as kubernetes namespace or job kind.
- `attemptIndex` (integer, optional) — The restart/attempt count for this job.
- `advice` (v1AdviceRecommendation, optional) — AdviceRecommendation represents the recommended state and node constraints.
- `issues` (list of v1Issue, optional) — Issues detected for this job.
- `createdAt` (datetime, optional) — When this advice was created.
- `updatedAt` (datetime, optional) — When this advice was last updated.
- `generation` (string, optional) — Desired-state generation. Changes only when scheduler-affecting intent changes.
- `reconciliationStatus` (v1AdviceReconciliationStatus, optional) — AdviceReconciliationStatus records one generation-scoped reconciliation observation.
- `desiredStateChangedAt` (datetime, optional) — When the current scheduler-affecting desired-state generation began.
- `recoveryContext` (v1RecoveryContext, optional) — RecoveryContext carries one durable recovery sequence's W3C trace context. It is correlation data and does not authorize or otherwise change scheduler actions.

### V1AdviceSchedulerMetadata

Scheduler metadata that is specific to the scheduler such as kubernetes namespace or job kind.

### v1AdviceRecommendation

AdviceRecommendation represents the recommended state and node constraints.

- `state` (enum, optional, default: ADVICE_STATE_UNSPECIFIED) — AdviceState represents the recommended state action for a job. - ADVICE_STATE_UNSPECIFIED: The state is not specified. - ADVICE_STATE_RESTARTED: The job should be restarted. - ADVICE_STATE_TERMINATED: The job should be terminated. - ADVICE_STATE_RELEASED: The exact job attempt should be scheduler-eligible.
  - Allowed values: `ADVICE_STATE_UNSPECIFIED`, `ADVICE_STATE_RESTARTED`, `ADVICE_STATE_TERMINATED`, `ADVICE_STATE_RELEASED`
- `nodeConstraints` (v1NodeConstraints, optional) — NodeConstraints defines node scheduling constraints for jobs.

### v1Issue

Issue represents a detected issue with a job.

- `issueType` (string, optional) — The type of issue detected.
- `timestamp` (datetime, optional) — When the issue was detected.
- `detectedBy` (string, optional) — What detected this issue (e.g., "watcher", "advisor").
- `relevantLogLines` (list of string, optional) — Relevant log lines related to the issue.
- `remediationActions` (list of v1RemediationAction, optional) — Actions taken to remediate this issue.

### v1AdviceReconciliationStatus

AdviceReconciliationStatus records one generation-scoped reconciliation observation.

- `observedGeneration` (string, optional) — Advice generation observed by the controller.
- `disposition` (enum, optional, default: ADVICE_RECONCILIATION_DISPOSITION_UNSPECIFIED) — AdviceReconciliationDisposition describes whether one Advice generation still needs work. - ADVICE_RECONCILIATION_DISPOSITION_UNSPECIFIED: The disposition is not specified. - ADVICE_RECONCILIATION_DISPOSITION_PENDING: Reconciliation has not reached a terminal observation. - ADVICE_RECONCILIATION_DISPOSITION_CONVERGED: Fresh scheduler state satisfies the desired state. - ADVICE_RECONCILIATION_DISPOSITION_ABANDONED: The desired state can no longer be reached for this generation.
  - Allowed values: `ADVICE_RECONCILIATION_DISPOSITION_UNSPECIFIED`, `ADVICE_RECONCILIATION_DISPOSITION_PENDING`, `ADVICE_RECONCILIATION_DISPOSITION_CONVERGED`, `ADVICE_RECONCILIATION_DISPOSITION_ABANDONED`
- `reason` (enum, optional, default: ADVICE_RECONCILIATION_REASON_UNSPECIFIED) — AdviceReconciliationReason is a bounded explanation for a reconciliation disposition. - ADVICE_RECONCILIATION_REASON_UNSPECIFIED: The reason is not specified. - ADVICE_RECONCILIATION_REASON_DESIRED_STATE_OBSERVED: Fresh scheduler state exactly matches the desired state. - ADVICE_RECONCILIATION_REASON_ALREADY_SATISFIED: The target already satisfied the desired state before an action was needed. - ADVICE_RECONCILIATION_REASON_ADVICE_EXPIRED: Ordinary Advice exceeded its configured maximum age. - ADVICE_RECONCILIATION_REASON_STALE_ATTEMPT: A newer persisted attempt is beyond this recommendation's applicability window. - ADVICE_RECONCILIATION_REASON_TARGET_STATE_FINAL: The target is final and cannot accept the recommendation. - ADVICE_RECONCILIATION_REASON_SUCCESSOR_ALREADY_RUNNING: A live successor cannot safely receive the required constraints. - ADVICE_RECONCILIATION_REASON_INVALID_RECOMMENDATION: The recommendation has no reconciliation path. - ADVICE_RECONCILIATION_REASON_UNSUPPORTED_RECOMMENDATION: The controller cannot implement the recommendation.
  - Allowed values: `ADVICE_RECONCILIATION_REASON_UNSPECIFIED`, `ADVICE_RECONCILIATION_REASON_DESIRED_STATE_OBSERVED`, `ADVICE_RECONCILIATION_REASON_ALREADY_SATISFIED`, `ADVICE_RECONCILIATION_REASON_ADVICE_EXPIRED`, `ADVICE_RECONCILIATION_REASON_STALE_ATTEMPT`, `ADVICE_RECONCILIATION_REASON_TARGET_STATE_FINAL`, `ADVICE_RECONCILIATION_REASON_SUCCESSOR_ALREADY_RUNNING`, `ADVICE_RECONCILIATION_REASON_INVALID_RECOMMENDATION`, `ADVICE_RECONCILIATION_REASON_UNSUPPORTED_RECOMMENDATION`
- `observedAt` (datetime, optional) — Time of the fresh scheduler or policy observation.
- `transitionedAt` (datetime, optional) — Time the disposition or reason last changed.
- `diagnosticMessage` (string, optional) — Optional bounded diagnostic text for operators.

### v1RecoveryContext

RecoveryContext carries one durable recovery sequence's W3C trace context. It is correlation data and does not authorize or otherwise change scheduler actions.

- `sequenceId` (string, required) — The durable recovery sequence UUID assigned by Job Manager.
- `traceparent` (string, required) — The canonical W3C traceparent for later recovery work.
- `triggeredAt` (datetime, required) — When the triggering condition was observed.
- `operation` (enum, required, default: RECOVERY_OPERATION_UNSPECIFIED) — RecoveryOperation identifies the scheduler-neutral recovery intent. - RECOVERY_OPERATION_UNSPECIFIED: No recovery operation was specified. - RECOVERY_OPERATION_RESTART: Restart the failed source attempt. - RECOVERY_OPERATION_TERMINATE: Terminate the source attempt. - RECOVERY_OPERATION_DAG_RELEASE: Release a held job after its DAG dependencies are satisfied.
  - Allowed values: `RECOVERY_OPERATION_UNSPECIFIED`, `RECOVERY_OPERATION_RESTART`, `RECOVERY_OPERATION_TERMINATE`, `RECOVERY_OPERATION_DAG_RELEASE`
- `tracestate` (string, optional) — The canonical W3C tracestate, when present.

### v1NodeConstraints

NodeConstraints defines node scheduling constraints for jobs.

- `exclusions` (list of string, optional) — List of nodes to exclude from job scheduling.
- `inclusions` (list of string, optional) — List of nodes to explicitly include for job scheduling.

### v1RemediationAction

RemediationAction represents an action taken to remediate an issue.

- `actionType` (string, optional) — The type of action (e.g., "exclude_node", "restart_job").
- `timestamp` (datetime, optional) — When the action was taken.
- `reason` (string, optional) — The reason for taking this action.
- `resourceDetails` (list of v1ResourceDetail, optional) — Resources affected by this action.

### v1ResourceDetail

ResourceDetail represents details about a specific resource.

- `resourceType` (string, optional) — The type of resource (e.g., "node", "gpu").
- `resourceId` (string, optional) — The unique identifier of the resource.
- `details` (string, optional) — Additional details about the resource.

## Examples

**Response**

```json
{
  "advice": [
    {
      "heimdallJobId": "string",
      "jobId": "string",
      "schedulerMetadata": {},
      "attemptIndex": 1,
      "advice": {
        "state": "ADVICE_STATE_UNSPECIFIED",
        "nodeConstraints": {
          "exclusions": [
            "string"
          ],
          "inclusions": [
            "string"
          ]
        }
      },
      "issues": [
        {
          "issueType": "string",
          "timestamp": "2024-01-15T09:30:00Z",
          "detectedBy": "string",
          "relevantLogLines": [
            "string"
          ],
          "remediationActions": [
            {
              "actionType": "string",
              "timestamp": "2024-01-15T09:30:00Z",
              "reason": "string",
              "resourceDetails": [
                {
                  "resourceType": "string",
                  "resourceId": "string",
                  "details": "string"
                }
              ]
            }
          ]
        }
      ],
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z",
      "generation": "string",
      "reconciliationStatus": {
        "observedGeneration": "string",
        "disposition": "ADVICE_RECONCILIATION_DISPOSITION_UNSPECIFIED",
        "reason": "ADVICE_RECONCILIATION_REASON_UNSPECIFIED",
        "observedAt": "2024-01-15T09:30:00Z",
        "transitionedAt": "2024-01-15T09:30:00Z",
        "diagnosticMessage": "string"
      },
      "desiredStateChangedAt": "2024-01-15T09:30:00Z",
      "recoveryContext": {
        "sequenceId": "string",
        "traceparent": "string",
        "triggeredAt": "2024-01-15T09:30:00Z",
        "operation": "RECOVERY_OPERATION_UNSPECIFIED",
        "tracestate": "string"
      }
    }
  ],
  "count": 1,
  "nextPageToken": "string"
}
```

**SDK Code**

```python
import requests

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

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'https://api.example.com/v1/advice';
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/advice"

	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/advice")

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/advice")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

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

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

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/v1/advice");
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/advice")! 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()
```