---
title: "Read trusted shadow coverage and gaps"
method: GET
path: "/v1/pools/{id}/shadow-runs"
tags: ["Pools"]
---

# Read trusted shadow coverage and gaps

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

Members may read retained cycles. Keyset pagination is bound to the same pool and kind. A gap is a completed elapsed hour without trusted evidence.

## Path parameters

- `id` string, required

## Query parameters

- `limit` integer
- `cursor` string
- `kind` 'idle_reclaim' | 'defragment' | 'drain_window' | 'wait_tuning'

## Response `200`

Read trusted shadow coverage and gaps

- PoolShadowRuns
  - `pool_id` string, required
  - `runs` PoolShadowRun[], required
    - `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.
  - `next_cursor` string, nullable, required

## 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)