---
title: "Retrieve all Tasks"
method: GET
path: "/v2/org/{org}/nico/task"
tags: ["Task"]
---

# Retrieve all Tasks

`GET /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.

## Query parameters

- `siteId` string, uuid, required
- `activeOnly` boolean
- `includeReport` boolean
- `pageNumber` integer — One-indexed page number.
- `pageSize` integer

## Response `200`

OK

- Task[]
  - `id` string, uuid — Unique identifier of the task.
  - `status` 'Unknown' | 'Pending' | 'Running' | 'Succeeded' | 'Failed' | 'Terminated' — Current state of the task.
  - `description` string — Human-readable description provided when the task was created.
  - `message` string — Optional status or error message describing the current state or result.
  - `ruleId` string, uuid, 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` string, date-time — Timestamp when the task started execution.
  - `finished` string, date-time — Timestamp when the task finished (succeeded, failed or terminated).
  - `created` string, date-time — Timestamp when the task was created.
  - `updated` string, date-time — Timestamp when the task was last updated.
  - `report` 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` 1, required — Schema version of this report. Always `1` for `TaskReportV1`.
    - `stages` TaskReportV1Stage[], required
      - `number` integer, required — 1-based rule stage number.
      - `status` 'pending' | 'running' | 'completed' | 'failed' | 'skipped', 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.
      - `steps` TaskReportV1Step[], required
        - `componentType` string, required — Component class this step targets, e.g. `Compute`, `NVLSwitch`, `PowerShelf`.
        - `status` 'pending' | 'running' | 'completed' | 'failed' | 'skipped', 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.
        - `totalComponents` integer — Count of components of `componentType` this step targets. Surfaced here because the task representation does not include the per-type component map.
        - `completedComponents` integer — Reserved for a future best-effort activity contract that reports per-component outcomes. Not written under the current fail-fast contract and omitted by the producer.
        - `failedComponents` integer — Reserved (see `completedComponents`).
        - `startedAt` string, date-time — Set when the step leaves `pending`. `skipped` steps carry no timestamp.
        - `finishedAt` string, date-time — Set when the step reaches a terminal state.
        - `error` string — Failure summary when `status == failed`. Truncated to 512 bytes.
      - `startedAt` string, date-time — Set when the stage leaves `pending`.
      - `finishedAt` string, date-time — Set when the stage reaches a terminal state.
      - `error` string — Failure summary when `status == failed`. Truncated to 512 bytes.
    - `error` string — 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.

## Other responses

- `400` — Error response when request data cannot be validated
- `403` — Error response when user is not authorized to call an endpoint or retrieve/modify objects
- `412` — Response when the API handler encounters an unexpected error
- `500` — Response when the API handler encounters an unexpected error
- `504` — 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.

## Changes

- **2026-08-26** `01e93520819d` — 1 info
  - removed the `Waiting` enum value from the `items/status` response property for the response status `200`
- **2026-08-25** `1eec34c175c9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/changes/v2/org/:org/nico/task/get.md)

---

[API](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api.md) · [All operations](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nvidia/nvidia-infra-controller-rest-api/revisions/2096eb1db2c1/schema)