---
title: "Read a pool forecast and its calibration"
method: GET
path: "/v1/pools/{id}/forecast"
tags: ["Pools"]
---

# Read a pool forecast and its calibration

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

## Request

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

Snapshot is null until the first refresh. Cached data remains readable while disabled or paused. Forecast availability is separate from empirical calibration availability.

## Path parameters

- `id` string, required

## Query parameters

- `horizon` 7 | 30

## Response `200`

Read a pool forecast and its calibration.

- PoolForecastResponse
  - `pool_id` string, required
  - `predict_enabled` boolean, required
  - `refresh_status` 'active' | 'disabled' | 'awaiting_refresh' | 'stale' | 'paused_credits' | 'paused_cap' | 'paused_payment' | 'consent_required', required
  - `subscription` PoolPredictSubscription, required: Customer-owned pools report byoc-free-v1 and monthly_micros 0, including while active. Free activation and refresh create no subscription charge. paid_current_period normally remains false. For non-cloud pools it records any retained historical funding for the current month, including credits or an accepted postpaid receivable. It does not assert that a postpaid invoice has been paid. Historical charges retain their original rate version and amount.
    - `status` 'active' | 'disabled' | 'paused_credits' | 'paused_cap' | 'paused_payment' | 'consent_required', required
    - `rate_version` string, required
    - `monthly_micros` integer, required
    - `period_start` string, date-time, required
    - `period_end` string, date-time, required
    - `paid_current_period` boolean, required
    - `enabled_pool_count` integer, required
  - `snapshot` PoolForecastSnapshot, required
    - `pool_id` string, required
    - `generated_at` string, date-time, required
    - `forecast` PoolForecast, required: Allocated device-hour demand including foreign allocations. A seasonal baseline requires 672 complete hourly observations. Unknown demand is not replaced with zero. No learned model is claimed unless its registry promotion was verified.
      - `model` string, required
      - `status` 'ready' | 'insufficient_history', required
      - `as_of` string, date-time, required
      - `horizon_days` 7 | 30, required
      - `history_from` string, date-time, required
      - `history_hours` integer, required
      - `required_history_hours` integer, required
      - `points` PoolForecastBand[], required
        - `hour` string, date-time, required
        - `p10` number, required
        - `p50` number, required
        - `p90` number, required
        - `queue_device_hours` number: Known queued demand added to this hourly band. Omitted for historical forecasts without queue evidence.
      - `queue` PoolForecastQueue: Retained queued demand under an immediate-start scenario from the next complete hour. This is not a placement promise. Unknown runtimes remain a job count. Known device-hours equal added device-hours plus demand beyond the selected horizon.
        - `method` 'retained_queue_immediate_start_v1', required
        - `observed_at` string, date-time, required
        - `known_jobs` integer, required
        - `unknown_jobs` integer, required
        - `known_device_hours` number, required
        - `added_device_hours` number, required
        - `outside_horizon_device_hours` number, required
    - `calibration` PoolForecastEvaluation, required: Last 30 completed UTC days scored only against forecasts issued before the target hour. Missing actuals are excluded and denominators are explicit. Daily coverage is the fraction of complete days with every hour covered, not a nominal 80 percent daily interval.
      - `from` string, date-time, required
      - `to` string, date-time, required
      - `status` 'no_data' | 'partial' | 'complete', required
      - `expected_hours` integer, required
      - `forecast_hours` integer, required
      - `evaluated_hours` integer, required
      - `covered_hours` integer, required
      - `hourly_coverage` number, nullable, required
      - `pinball_p10` number, nullable, required
      - `pinball_p50` number, nullable, required
      - `pinball_p90` number, nullable, required
      - `complete_days` integer, required
      - `covered_days` integer, required
      - `daily_coverage` number, nullable, required
    - `owned_devices` integer, required
    - `advisory_burst_price` PoolAdvisoryPrice, required: Fresh compatible available market configuration observed with the customer markup. Device-fit hourly advisory only, not a workload completion quote or an executable reservation.
      - `rate_micros_per_device_hour` integer, required
      - `observed_at` string, date-time, required
      - `basis` string, 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)