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

# Retrieve a Task

`GET /v2/org/{org}/nico/task/{id}`

Get a Task by UUID.

The same handler is also mounted at `/v2/org/{org}/nico/rack/task/{id}` for
backward compatibility; prefer this path for new clients.

Tasks are site-scoped; `siteId` must be the Site where the task was created.
Org must have an Infrastructure Provider entity. User must have authorization role with `PROVIDER_ADMIN` suffix.

## Query parameters

- `siteId` string, uuid, required

## Response `200`

OK

- Task — A task representing an asynchronous, site-scoped operation against rack, tray, or other site infrastructure.
  - `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
- `404` — Error response when requested object is not found
- `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 `status` response property for the response status `200`
- **2026-08-14** `441cfc1afc1c` — 1 info
  - added the non-success response with the status `504`
- **2026-06-10** `9a135fa35aad` — 1 info
  - added the optional property `ruleId` to the response with the `200` status
- **2026-06-09** `76f39047188e` — 1 info
  - added the optional property `report` to the response with the `200` status
- **2026-06-02** `b078e63260c1` — 1 info
  - endpoint added

[Full history](https://skmtc.dev/nvidia/apis/nvidia-infra-controller-rest-api/changes/v2/org/:org/nico/task/:id/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)