---
title: "Start a future shadow observation cycle"
method: POST
path: "/v1/pools/{id}/shadow-runs"
tags: ["Pools"]
---

# Start a future shadow observation cycle

`POST /v1/pools/{id}/shadow-runs`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/pools/{id}/shadow-runs`
- Auth: HTTP bearer

Requires an account admin, active Predict, active Route authorization and the kill switch off. Starts at the next complete UTC hour and runs for 168 hours. Starting the same configuration within one hour returns the existing cycle. No action is applied by shadow mode.

## Path parameters

- `id` string, required

## Request body

- PoolActionPolicyRequest
  - `kind` 'idle_reclaim' | 'defragment' | 'drain_window' | 'wait_tuning', required
  - `level` 'off' | 'recommend' | 'approve' | 'auto', required
  - `window_cron` string, required: Weekly UTC minute hour * * weekday. Minute, hour and weekday accept *, integer lists and inclusive ranges. No steps, names, macros, duplicate values or leading zeros. Weekday 0 is Sunday.
  - `parallelism_cap` integer, required

## Response `201`

Start a future shadow observation cycle

- PoolShadowRun: A future 168-hour observation cycle. Missing capture is a gap, never fabricated evidence. Only idle reclaim currently has a trusted producer. Completed generic evidence cannot qualify automatic actions.
  - `id` string, required
  - `pool_id` string, required
  - `kind` 'idle_reclaim' | 'defragment' | 'drain_window' | 'wait_tuning', required
  - `window_cron` string, required: Weekly UTC minute hour * * weekday. Minute, hour and weekday accept *, integer lists and inclusive ranges. No steps, names, macros, duplicate values or leading zeros. Weekday 0 is Sunday.
  - `parallelism_cap` integer, required
  - `cycle_start` string, date-time, required
  - `cycle_end` string, date-time, required
  - `state` 'running' | 'completed', required
  - `ended_at` string, date-time, nullable, required
  - `trusted_hours` integer, required
  - `elapsed_hours` integer, required
  - `gap_hours` integer, required
  - `would_have_acted` integer, required: Sum of counterfactual action counts from trusted observations. Never measured savings or an applied-action count.
  - `producer_available` boolean, required
  - `qualifies_auto` boolean, required: This exact cycle has 168 trusted hours, is completed and ended within 30 days. Current entitlement, policy, permissions and kill switch are checked separately.

## Other responses

- `default`: Authentication, disabled feature, invalid input, missing pool or host, rate limits, and transient failures apply.

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)