--- title: "Create a Task Run" method: POST path: "/v2/org/{org}/nico/task/run" tags: ["Task Run"] --- # Create a Task Run `POST /v2/org/{org}/nico/task/run` Create a Task Run: a phased, policy-gated execution of one operation across many Racks. The configuration is validated server-side by Flow; on validation failure no state changes. A Task Run executes exactly one operation over a candidate set of Racks, narrowed by an optional `selector` and divided into phases by an optional `options.phasePolicy`. The response echoes the assigned `id`; the Task Run always starts in the `Pending` state. Poll `GET /task/run/{id}` for progress. Org must have an Infrastructure Provider entity. User must have authorization role with `PROVIDER_ADMIN` suffix. ## Request body - CreateTaskRunRequest — Request body for creating a Task Run. `operationType` is inferred from the operation and is not accepted here. Flow performs semantic validation (selector ranges, phase math, operation code membership) server-side. - `siteId` string, uuid, required — ID of the Site to create the Task Run on. - `name` string, required — Human-readable name of the Task Run. - `description` string — Optional free-form description. - `selector` TaskRunSelector — Selects a subset of candidate Racks. Percentage is the only supported selector today. - `percentage` TaskRunPercentageSelector — Selects a percentage of the candidate Racks. `seed` is optional; when omitted Flow generates and stores one so the cohort is deterministic and auditable. - `percent` integer, required — Percentage of candidate Racks to select. - `seed` string — Optional seed for the deterministic selection. - `options` TaskRunOptions, required — Execution policy for the Task Run. - `maxConcurrentTargets` integer, required — Caps how many targets may have active child Tasks at once. Must be greater than zero. - `safetyPolicy` TaskRunSafetyPolicy — A set of gates that pause the Task Run when any one of them trips (OR composition). - `gates` TaskRunSafetyGate[] — Safety gates evaluated after each target outcome. - `failureRate` TaskRunFailureRateGate — Pauses when the failed/planned ratio reaches `thresholdPercent` for the scope. - `scope` 'currentPhase' | 'cumulativeRun' — Whether the ratio is evaluated over the current phase or the cumulative run. - `thresholdPercent` integer, required — Failure-rate percentage at which the gate trips. - `failureCount` TaskRunFailureCountGate — Pauses when the number of failed targets reaches `thresholdCount` for the scope. - `scope` 'currentPhase' | 'cumulativeRun' — Whether the count is evaluated over the current phase or the cumulative run. - `thresholdCount` integer, required — Number of failed targets at which the gate trips. - `conflictPolicy` TaskRunConflictPolicy — Configures how blocked targets are retried. Retry is the only supported strategy today. - `retry` TaskRunConflictRetry — Retry backoff for blocked targets. Durations are Go duration strings (e.g. `30m`, `10s`); an empty value means "use the operation default". - `retryTimeout` string — Total time to keep retrying a blocked target before giving up, as a Go duration string (e.g. `30m`, `2h`). - `initialRetryDelay` string — Delay before the first retry, as a Go duration string (e.g. `10s`, `1m`). - `maxRetryDelay` string — Cap on the exponentially growing retry delay, as a Go duration string (e.g. `5m`). - `orderingPolicy` TaskRunOrderingPolicy — Controls the order in which targets are processed. Random is the only supported ordering today. - `random` TaskRunRandomOrdering — Orders targets randomly. `seed` is optional; Flow generates and stores one when omitted. - `seed` string — Optional seed for the deterministic random ordering. - `phasePolicy` TaskRunPhasePolicy — Divides the selected targets into phases. Set at most one of `equal`, `percentage`, or `count`; omit the whole policy for a single phase covering all targets. - `equal` TaskRunEqualPhases — Splits targets into `phaseCount` roughly equal phases. The request is rejected when `phaseCount` exceeds the number of selected targets, because every configured phase must contain at least one target. - `phaseCount` integer, required — Number of equally sized phases. - `percentage` TaskRunPercentagePhases — Splits targets by percentage. Values must sum to 100. A configured phase must resolve to at least one selected target after rounding or the request is rejected. - `phases` integer[], required — Per-phase percentages, in phase order; must sum to 100. - `count` TaskRunCountPhases — Splits targets by explicit counts. A generated final phase covers any remaining targets. - `phases` integer[], required — Per-phase target counts, in phase order. - `autoAdvance` boolean — When true, phases advance automatically as long as safety gates are not tripped. When false (default) each completed phase pauses at a phase gate until advanced explicitly. - `operation` TaskRunOperation, required — The operation the Task Run executes. Firmware is the only supported operation. - `firmware` TaskRunFirmwareOperation, required — Configures a firmware rollout. - `version` string, required — Target firmware version to roll out. - `ruleId` string, uuid, nullable — Operation Rule to pin for each target's firmware Task. Null to let Flow's default rule resolution pick one. - `overrideReadinessCheck` boolean — Skip the pre-flight readiness check when true. - `subTargets` string[] — Optional subset of firmware sub-parts to update within each targeted tray, using the same lowercase names as the Tray firmware endpoint's `targets` (e.g. `bmc`, `bios`). Omitted or empty means update everything in the bundle. Unknown names are rejected. - `excludeRunIds` string[] — Excludes Racks materialized by prior Task Runs from this Task Run's candidate scope. ## Response `201` Task Run was created. - 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 - `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-19** `484497856a94` — 7 breaking - the `options/maxConcurrentTargets` request property type/format changed from `integer`/`` to `integer`/`int32` - the `options/phasePolicy/count/phases/items/` request property type/format changed from `integer`/`` to `integer`/`int32` - the `options/phasePolicy/equal/phaseCount` request property type/format changed from `integer`/`` to `integer`/`int32` - the `options/phasePolicy/percentage/phases/items/` request property type/format changed from `integer`/`` to `integer`/`int32` - …3 more - **2026-08-18** `c459c6587dee` — 7 breaking - the `options/phasePolicy/count/phases/items/` request property's min was increased to `1.00` - the `options/phasePolicy/percentage/phases/items/` request property's min was increased to `1.00` - the `options/safetyPolicy/gates/items/failureCount/thresholdCount` request property's min was increased to `1.00` - the `options/safetyPolicy/gates/items/failureRate/thresholdPercent` request property's min was increased to `1.00` - …3 more - **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/post.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)