---
title: "Read advisory pool recommendations"
method: GET
path: "/v1/pools/{id}/recommendations"
tags: ["Pools"]
---

# Read advisory pool recommendations

`GET /v1/pools/{id}/recommendations`

## Request

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

Read advice and human-reported outcomes for this customer-owned pool. Results use keyset pagination in descending creation order. No execution or automatic action is performed.

## Path parameters

- `id` string, required

## Query parameters

- `limit` integer
- `cursor` string
- `state` 'open' | 'done' | 'expired'

## Response `200`

Read advisory pool recommendations.

- PoolRecommendationsResponse: One page of advice and recorded human outcomes, newest first. Follow next_cursor to read older records. Use state=open for current actionable advice.
  - `pool_id` string, required
  - `predict_enabled` boolean, required
  - `refresh_status` 'active' | 'disabled' | 'awaiting_refresh' | 'stale' | 'paused_credits' | 'paused_cap' | 'paused_payment' | 'consent_required', required
  - `recommendations` PoolRecommendation[], required
    - `id` string, required
    - `pool_id` string, required
    - `kind` 'rightsize' | 'idle_reclaim' | 'drain_window' | 'defragment' | 'wait_tuning', required
    - `generated_at` string, date-time, required
    - `expires_at` string, date-time, required
    - `state` 'open' | 'done' | 'expired', required
    - `recommendation` union, required
      - PoolRightSizeRecommendation
        - `kind` 'rightsize', required
        - `level` 'recommend', required
        - `risk` 'low' | 'medium' | 'high', required
        - `recommended_devices` integer, required
        - `expected_savings_micros` integer, required
        - `evidence` PoolRightSizeEvidence, required: Recomputable prospective scenario costs in USD micros. Uses allocated demand and the observed hourly market price. Expected savings are not measured outcomes or guaranteed cost to completion.
          - `method` string, required
          - `history_from` string, date-time, required
          - `history_to` string, date-time, required
          - `history_hours` integer, required
          - `horizon_from` string, date-time, required
          - `horizon_to` string, date-time, required
          - `horizon_hours` integer, required
          - `scenarios_per_hour` integer, required
          - `current_devices` integer, required
          - `released_devices` integer, required
          - `owned_micros_per_device_hour` integer, required
          - `burst_micros_per_device_hour` integer, required
          - `critical_fractile` number, required
          - `expected_burst_device_hours` number, required
          - `expected_burst_micros` integer, required
          - `released_owned_micros` integer, required
          - `advisory_price` boolean, required
          - `demand_distribution` PoolDemandMass[], required
            - `device_hours` number, required
            - `scenario_count` integer, required
      - PoolIdleRecommendation: Advisory device allocation with SM below 5 percent for an uninterrupted 30 minutes, supported by one week of observed hourly history. Foreign is only a boolean. No process identity or measured savings are inferred. Evidence expires after three minutes.
        - `kind` 'idle_reclaim', required
        - `level` 'recommend', required
        - `risk` 'high', required
        - `advisory_only` true, required
        - `host_id` string, required
        - `device_id` string, required
        - `device_index` integer, required
        - `expected_savings_micros` unknown, required
        - `expires_at` string, date-time, required
        - `evidence` PoolIdleEvidence, required
          - `method` string, required
          - `sm_util_below_pct` integer, required
          - `trigger_from` string, date-time, required
          - `trigger_to` string, date-time, required
          - `consecutive_seconds` integer, required
          - `observed_through` string, date-time, required
          - `foreign` boolean, required
          - `history_from` string, date-time, required
          - `history_to` string, date-time, required
          - `historical_observed_hours` integer, required
      - PoolDrainRecommendation: A retained UTC drain window with at least three hours remaining at generation. The window may start in the current hour. Expiry is no later than window_to and 24 hours after generation. No measured or estimated saving is invented.
        - `kind` 'drain_window', required
        - `level` 'recommend', required
        - `risk` 'high', required
        - `advisory_only` true, required
        - `host_id` string, required
        - `expected_savings_micros` unknown, required
        - `expires_at` string, date-time, required
        - `evidence` PoolDrainEvidence, required
          - `method` string, required
          - `window_from` string, date-time, required
          - `window_to` string, date-time, required
          - `consecutive_hours` integer, required
          - `threshold_devices` integer, required
          - `max_p90_device_hours` number, required
          - `history_from` string, date-time, required
          - `history_to` string, date-time, required
          - `history_hours` integer, required
          - `model` string, required
      - PoolDefragmentRecommendation: Manual placement advice from 336 fully observed Route hours. No advice is produced from missing placement observations. Foreign jobs are never proposed for movement and savings are not inferred.
        - `kind` 'defragment', required
        - `level` 'recommend', required
        - `risk` 'high', required
        - `advisory_only` true, required
        - `expected_savings_micros` unknown, required
        - `expires_at` string, date-time, required
        - `evidence` PoolDefragmentEvidence, required
          - `method` string, required
          - `history_from` string, date-time, required
          - `history_to` string, date-time, required
          - `observed_hours` integer, required
          - `fragmentation_wait_seconds` number, required
          - `threshold_seconds` number, required
          - `packing_policy` string, required
          - `foreign_jobs_movable` false, required
      - PoolWaitTuningRecommendation: At most 25 percent adjustment based on 336 hours of actual Route coverage and completed settled executions. Applies to future waits. No counterfactual savings or universal delay guarantee.
        - `kind` 'wait_tuning', required
        - `level` 'recommend', required
        - `risk` 'high', required
        - `advisory_only` true, required
        - `expected_savings_micros` unknown, required
        - `expires_at` string, date-time, required
        - `evidence` PoolWaitTuningEvidence, required
          - `observed_hours` 336, required
          - `completed_executions` integer, required
          - `wait_seconds` integer, required
          - `runtime_seconds` integer, required
          - `burst_spent_micros` integer, required
          - `policy_version` integer, required
          - `observed_delay_pct` number, required
          - `waiting_budget_pct` number, required
          - `current_alpha` number, required
          - `proposed_alpha` number, required
          - `method` 'bounded_proportional_wait_v1', required
          - `history_from` string, date-time, required
          - `history_to` string, date-time, required
          - `source_sha256` string, required
    - `outcome` PoolRecommendationOutcome, required: Immutable customer-reported manual outcome. reported_saving_micros is optional customer testimony, not measured or verified savings. No action is executed by recording an outcome.
      - `recorded_at` string, date-time, required
      - `outcome` string, required
      - `reported_saving_micros` integer, nullable, required
  - `next_cursor` string, nullable, required: Opaque continuation cursor or null when no older records remain. Reuse the same state filter.

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