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

# Retrieve a Task Run

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

Get a Task Run by UUID. Set `includeStats=true` for derived per-phase
outcome counts (current phase and cumulative run).

Task Runs are site-scoped; `siteId` must be the Site that owns the
Task Run. Org must have an Infrastructure Provider entity. User must have
authorization role with `PROVIDER_ADMIN` suffix.

## Query parameters

- `siteId` string, uuid, required
- `includeStats` boolean

## Response `200`

OK

- TaskRun — A Task Run is a phased, policy-gated execution of one operation across many Racks. List responses populate the summary fields; the single-Task-Run `GET` additionally populates `stats` when `includeStats=true`.
  - `id` string, uuid, required — Unique identifier of the Task Run.
  - `name` string, required — Human-readable name of the Task Run.
  - `description` string — Optional free-form description.
  - `operationType` 'PowerControl' | 'FirmwareControl', required — Type of operation this Task Run executes. Currently always `FirmwareControl`.
  - `operationCode` string — Operation code within the operation type (e.g. `upgrade`).
  - `status` 'Unknown' | 'Pending' | 'Running' | 'Paused' | 'Completed' | 'Cancelled' | 'Failed' | 'CompletedWithFailures', required — Current lifecycle state of the Task Run.
  - `statusReason` 'Unknown' | 'None' | 'OperatorPaused' | 'PhaseGate' | 'SafetyGate' | 'ConflictRetryTimeout', required — Why the Task Run is paused or terminal (e.g. `PhaseGate`, `SafetyGate`). `None` when there is no qualifying reason.
  - `statusMessage` string — Optional human-readable detail for the current status.
  - `totalPhases` integer, required — Total number of phases the selected targets were divided into.
  - `created` string, date-time, required — Timestamp when the Task Run was created.
  - `updated` string, date-time, required — Timestamp when the Task Run was last updated.
  - `started` string, date-time, nullable — Timestamp when the Task Run started execution. Null before it starts.
  - `finished` string, date-time, nullable — Timestamp when the Task Run reached a terminal state. Null while active.
  - `stats` TaskRunStats — Summarizes target outcomes for the active phase and cumulatively across all phases processed so far.
    - `currentPhase` TaskRunPhaseStats, required — Summarizes target outcomes for one phase scope.
      - `phaseIndex` integer, required — Zero-based index of the phase this scope refers to.
      - `selectedTargets` integer, required — Number of targets selected within the scope.
      - `outcomeCounts` TaskRunOutcomeCounts, required — Counts terminal target outcomes within a phase scope.
        - `completed` integer, required — Targets that completed successfully.
        - `failed` integer, required — Targets that failed.
        - `terminated` integer, required — Targets that were terminated (e.g. by cancellation).
        - `skipped` integer, required — Targets that were skipped.
    - `cumulativePhase` TaskRunPhaseStats, required — Summarizes target outcomes for one phase scope.
      - `phaseIndex` integer, required — Zero-based index of the phase this scope refers to.
      - `selectedTargets` integer, required — Number of targets selected within the scope.
      - `outcomeCounts` TaskRunOutcomeCounts, required — Counts terminal target outcomes within a phase scope.
        - `completed` integer, required — Targets that completed successfully.
        - `failed` integer, required — Targets that failed.
        - `terminated` integer, required — Targets that were terminated (e.g. by cancellation).
        - `skipped` integer, required — Targets that were skipped.

## 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-14** `441cfc1afc1c` — 1 info
  - added the non-success response with the status `504`
- **2026-07-29** `ac0607a42081` — 1 info
  - endpoint added

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