---
title: "Get a served probabilistic forecast"
method: GET
path: "/api/v1/grid/forecasts"
tags: ["Forecast"]
---

# Get a served probabilistic forecast

`GET /api/v1/grid/forecasts`

## Request

- Base URL: `https://askthegrid.com`
- URL: `https://askthegrid.com/api/v1/grid/forecasts`
- Auth: HTTP bearer

Read /api/v1/grid/forecast-capabilities for published models, variables, markets, target kinds, horizons, quantiles and vintage modes. Select a source or model and variable; requests without selectors remain price reads. Metis 1 Preview currently serves price at settlement points: hubs (HB_*), load zones (LZ_*) and resource nodes use targetKind=node. Other registered variables use their published native targets and units. Omitting both dates on a latest read returns the requested horizon. Each point carries the point forecast and compatibility p10/p50/p90 fields, plus requested published levels in levels; source.quantiles names the returned set. Where available, bucketProbabilities and distributionSupports describe the full interval distribution. These are marginal distributions per interval, not joint scenarios. vintageMode=historical-comparison stitches no-hindsight vintages for evaluation, each settled target from the earliest run that covered it; vintageMode=latest-before stitches the newest run issued before each settled target, or at least leadHours before it. vintageMode=auction-matched returns, for each delivery interval whose day-ahead auction has closed, the newest run issued at or before that market's day-ahead deadline: the forecast a day-ahead bidder could have used. Historical windows are capped at 48 hours; auction-matched and latest-before with leadHours at 8 days. detail=levels omits bucket probabilities and supports.

## Query parameters

- `sourceId` string: Serving source id from forecast capability discovery.
- `modelId` string: Stable model id; the returned modelVersion and modelHash identify its serving build.
- `variable` string: price, load or generation, subject to serving capabilities. Existing requests default to price.
- `horizonHours` string: Forward hours, bounded by the selected source. Used to construct the window when both from and to are omitted.
- `quantiles` string: Comma-separated published levels, e.g. 0.05,0.5,0.95. Compatibility p10/p50/p90 fields remain available.
- `iso` union
  - ''
  - string
- `targetKind` string
- `targetId` string
- `from` string
- `to` string
- `asOf` string
- `vintageMode` string
- `leadHours` string
- `detail` string

## Response `200`

Success

- object
  - `delivery` object
    - `truncated` boolean, required
    - `totalRows` integer, required
    - `rowsReturned` integer, required
  - `iso` 'ERCOT' | 'NYISO' | 'CAISO' | 'PJM' | 'MISO' | 'ISONE' | 'SPP' | 'BPAT' | 'TVA' | 'DUK' | 'CPLE' | 'CPLW' | 'FPC' | 'FPL' | 'SOCO' | 'BCA' | 'AESO' | 'IESO' | 'CENACE' | 'HQ' | 'BCH' | 'MHEB' | 'SPC' | 'NBSO' | 'NSIESO', required
  - `target` object, required
    - `kind` 'node' | 'zone' | 'system' | 'fuel' | 'station', required
    - `id` string, required
  - `from` string, required
  - `to` string, required
  - `viewerTier` 'free' | 'enterprise', required
  - `series` object[], required
    - `access` union
      - object
        - `kind` 'organization', required
        - `id` string, uuid, required
        - `name` string, required
        - `slug` string, required
        - `logoUrl` string, uri, nullable
      - object
        - `kind` 'plan', required
        - `id` string, required
        - `name` string, required
      - object
        - `kind` 'plugin', required
        - `id` string, required
        - `name` string, required
        - `iconUrl` string, uri, nullable
    - `source` object, required
      - `variable` 'price' | 'load' | 'generation' | 'weather'
      - `id` string, required
      - `displayName` string, required
      - `shortName` string, required
      - `provider` string, required
      - `modelId` string, required
      - `infoHref` string
      - `description` string, required
      - `metric` string, required
      - `unit` string, required
      - `resolutionMinutes` number, required
      - `issueCadenceMinutes` number, required
      - `horizonHours` number, required
      - `contextHours` number, required
      - `quantiles` number[], required
      - `color` string, required
      - `requiredTier` 'free' | 'enterprise', required
    - `status` 'ready' | 'empty' | 'locked' | 'restricted', required
    - `issuedAt` string, nullable, required
    - `mirrorUpdatedAt` string, nullable
    - `contextStart` string, nullable, required
    - `contextEnd` string, nullable, required
    - `points` object[], required
      - `ts` string, required
      - `intervalSeconds` integer
      - `issuedAt` string
      - `point` number, required
      - `p10` number, required
      - `p50` number, required
      - `p90` number, required
      - `levels` object
      - `bucketProbabilities` number[]
      - `distributionSupportId` string
      - `actual` number, nullable
      - `modelVersion` string, nullable
    - `distributionSupports` object
    - `nodeCoverage` object
      - `status` 'supported' | 'unsupported', required
      - `modelHash` string, required
    - `vintageMode` 'latest' | 'historical-comparison' | 'latest-before' | 'auction-matched'
    - `modelVersion` string, nullable
    - `modelHash` string, nullable
    - `accuracy` object, nullable
      - `scored` number, required
      - `mae` number, required
      - `rmse` number, required
      - `maeP50` number, required
      - `quantileScore` number
      - `crps` number, required
      - `coverage` number, required
      - `pinball` object, required
        - `p10` number, required
        - `p50` number, required
        - `p90` number, required
      - `pinballByLevel` object
      - `scoredLevels` number[]
    - `upgradeHref` string

## Other responses

- `400`: The request did not match the contract.
- `401`: Missing or invalid credentials.
- `429`: Rate limit exceeded. Wait `Retry-After` seconds; `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` report the budget. Signed-in sessions and API keys have larger budgets than anonymous callers.

---

[API](https://skmtc.dev/askthegrid/apis/ask-the-grid-api.md) · [All operations](https://skmtc.dev/askthegrid/apis/ask-the-grid-api/llms.txt) · [OpenAPI document](https://skmtc.dev/askthegrid/apis/ask-the-grid-api/revisions/9cd80115e395?raw)