> This page is for NVIDIA Infra Controller.

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

# Retrieve all Tasks

GET https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/task

List all Tasks created in the specified Site, across every Rack and Tray.

Org must have an Infrastructure Provider entity. User must have authorization role with `PROVIDER_ADMIN` suffix, and the Site must belong to that Provider and have NICo Flow enabled.

Setting `activeOnly=true` restricts the result to tasks in a non-terminal REST state (`Pending` or `Running`). Results are ordered by creation time descending, then Task UUID descending, before pagination. The `X-Pagination` response header reports the total count over the post-filter set.

By default the `report` field is omitted from each Task in the response. Set `includeReport=true` to include it; this is opt-in because report bodies can be several KB.

Reference: https://docs.nvidia.com/infra-controller/rest-api-reference/api-reference/task/get-all-tasks

## Authentication

- `Authorization` header (bearer token, required) — ``` export JWT_BEARER_TOKEN="<jwt-bearer-token>" # Example org name: "acme-inc export ORG_NAME=<org-name> # Use the JWT bearer token in your API request auth header: curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current ```

## Request

### Path parameters

- `org` (string, required) — Name of the Org

### Query parameters

- `siteId` (string, required) — ID of the Site whose Tasks are returned.
- `activeOnly` (boolean, optional, default: false) — Restrict results to non-terminal Tasks.
- `includeReport` (boolean, optional, default: false) — Include the per-task execution report on each returned Task.
- `pageNumber` (integer, optional) — Page number for pagination query.
- `pageSize` (integer, optional, default: 20) — Number of Tasks returned per page.

## Response

### 200

OK

- `list of Task`

## Errors

### 400 Bad Request Error

Error response when request data cannot be validated

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 403 Forbidden Error

Error response when user is not authorized to call an endpoint or retrieve/modify objects

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 412 Precondition Failed Error

Response when the API handler encounters an unexpected error

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 500 Internal Server Error

Response when the API handler encounters an unexpected error

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 504 Gateway Timeout Error

The Site did not return a result within the request budget allocated to Site communication within the request cycle. This can occur if the Site Controller is down or under heavy request load. Operations are in general safe to retry. In rare cases, operations that create or update resources may succeed even if timeout is returned.

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

## Types

### Task

A task representing an asynchronous, site-scoped operation against rack, tray, or other site infrastructure.

- `id` (string, optional) — Unique identifier of the task.
- `status` (enum, optional) — Current state of the task.
  - Allowed values: `Unknown`, `Pending`, `Running`, `Succeeded`, `Failed`, `Terminated`
- `description` (string, optional) — Human-readable description provided when the task was created.
- `message` (string, optional) — Optional status or error message describing the current state or result.
- `ruleId` (string, optional, nullable) — Operation Rule that Flow resolved for this task — either because the caller pinned one via `ruleId` on the originating request or because Flow's default rule resolution picked it. Null if Flow has not yet recorded a resolution.
- `started` (datetime, optional) — Timestamp when the task started execution.
- `finished` (datetime, optional) — Timestamp when the task finished (succeeded, failed or terminated).
- `created` (datetime, optional) — Timestamp when the task was created.
- `updated` (datetime, optional) — Timestamp when the task was last updated.
- `report` (TaskReportV1, optional) — Structured v1 execution report for the task. Populated on single-task `GET` and `cancel` responses, and on list responses only when `includeReport=true` is set. Omitted when the task has not yet produced a report (e.g. still queued) or when the caller did not opt in on list endpoints. A future schema revision will be exposed as a new `TaskReportV2` schema referenced from a parallel response field; v1 consumers are not disturbed by that bump.

### NiCoApiErrorData

Additional data about the error

### TaskReportV1

Structured execution report (version 1) for a Flow-scheduled task. The document mirrors the structure of the operation rule that drives the workflow: each `Stage` corresponds to one rule stage and each `Step` within a stage corresponds to one rule sequence step at the same index. Clients pick the decoder by the `version` field; future report schemas will be exposed as `TaskReportV2` etc. and conveyed via a parallel response field, leaving v1 consumers untouched.

- `version` (enum, required) — Schema version of this report. Always `1` for `TaskReportV1`.
  - Allowed values: `1`
- `stages` (list of TaskReportV1Stage, required)
- `error` (string, optional) — Top-level failure summary: the message from the first stage that fails in this report. Not overwritten by subsequent failures, so it remains the canonical task-level error. Truncated to 512 bytes by the producer.

### TaskReportV1Stage

Execution state of one rule stage. `number` is the canonical key for joining a stage record back to its rule entry.

- `number` (integer, required) — 1-based rule stage number.
- `status` (enum, required) — Per-stage and per-step execution status. - `pending` — workflow has not yet reached this stage/step. - `running` — execution is in progress. - `completed` — execution finished successfully. - `failed` — execution finished with an error; see `error`. - `skipped` — the rule lists this component type but the task targets no components of that type, so the workflow will not invoke it.
  - Allowed values: `pending`, `running`, `completed`, `failed`, `skipped`
- `steps` (list of TaskReportV1Step, required)
- `startedAt` (datetime, optional) — Set when the stage leaves `pending`.
- `finishedAt` (datetime, optional) — Set when the stage reaches a terminal state.
- `error` (string, optional) — Failure summary when `status == failed`. Truncated to 512 bytes.

### TaskReportV1Step

Execution state of one rule sequence step. Pairs 1:1 with the rule's ordered steps within the containing stage and shares its index. Unresolved components (`totalComponents - succeededComponents - failedComponents`) have no reported terminal outcome, even if the step has failed or timed out.

- `componentType` (string, required) — Component class this step targets, e.g. `Compute`, `NVLSwitch`, `PowerShelf`.
- `status` (enum, required) — Per-stage and per-step execution status. - `pending` — workflow has not yet reached this stage/step. - `running` — execution is in progress. - `completed` — execution finished successfully. - `failed` — execution finished with an error; see `error`. - `skipped` — the rule lists this component type but the task targets no components of that type, so the workflow will not invoke it.
  - Allowed values: `pending`, `running`, `completed`, `failed`, `skipped`
- `totalComponents` (integer, required) — Count of components of `componentType` this step targets, including zero for skipped steps.
- `succeededComponents` (integer, required) — Number of requested components reported as successfully completed, combining the latest successful poll of the current batch with outcomes from completed batches. May decrease if a component is absent from a later poll. Zero when no successful outcomes have been reported.
- `failedComponents` (integer, required) — Number of requested components reported as `Failed`, using the same counting rules as `succeededComponents`. Zero when no failed outcomes have been reported.
- `startedAt` (datetime, optional) — Set when the step leaves `pending`. `skipped` steps carry no timestamp.
- `finishedAt` (datetime, optional) — Set when the step reaches a terminal state.
- `error` (string, optional) — Failure summary when `status == failed`. Truncated to 512 bytes.

## Examples

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Running",
    "description": "Power on rack components",
    "message": "Processing 3 of 5 components"
  }
]
```

**SDK Code**

```python example-1
import requests

url = "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task"

querystring = {"siteId":"siteId"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript example-1
const url = 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task?siteId=siteId';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

```go example-1
package main

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

func main() {

	url := "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task?siteId=siteId"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

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

}
```

```ruby example-1
require 'uri'
require 'net/http'

url = URI("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task?siteId=siteId")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

```java example-1
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task?siteId=siteId")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task?siteId=siteId', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp example-1
using RestSharp;

var client = new RestClient("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task?siteId=siteId");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift example-1
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task?siteId=siteId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```