---
title: "List Forecast Runs"
method: GET
path: "/runs/"
tags: ["Forecasts"]
---

# List Forecast Runs

`GET /runs/`

## Request

- Base URL: `https://api.modoenergy.com/pub/v1/forecasts`
- URL: `https://api.modoenergy.com/pub/v1/forecasts/runs/`
- Auth: API key in header `X-token`

Returns a paginated list of forecast runs for your company, ordered newest first by default.

Each item includes the original `simulation_config` submitted at creation. Use `GET /runs/{id}/results/{resolution}/` to retrieve results for a completed run.

Filtering: combine any of the query parameters below — they are AND'd together. `*__in` parameters accept comma-separated values. Date filters accept any ISO 8601 datetime, e.g. `2026-01-01T00:00:00Z`.

## Query parameters

- `created_at_after` string, date-time
- `created_at_before` string, date-time
- `status` 'draft' | 'processing' | 'ready_for_review' | 'failed'
- `status__in` string
- `market_region` 'CAISO' | 'DE' | 'ERCOT' | 'ES' | 'GB' | 'ISONE' | 'IT' | 'MISO' | 'NEM' | 'NYISO' | 'PJM' | 'PL' | 'SPP'
- `market_region__in` string
- `scenario` string
- `scenario__in` string
- `run_name` string
- `f_model_version_used` string
- `f_model_version_used__in` string
- `ordering` 'created_at' | '-created_at'
- `limit` integer
- `offset` integer

## Response `200`

Paginated list of forecast runs.

- PaginatedForecastRunResponse
  - `count` integer: Total number of results.
  - `next` string, uri, nullable
  - `previous` string, uri, nullable
  - `results` ForecastRunListItem[]
    - `created_at` string, date-time: When the run was submitted.
    - `f_model_version_used` string: The fundamentals model version used to generate this run (e.g. Jan-26).
    - `id` string, uuid: Unique ID of the forecast run.
    - `market_region` 'CAISO' | 'DE' | 'ERCOT' | 'ES' | 'GB' | 'ISONE' | 'IT' | 'MISO' | 'NEM' | 'NYISO' | 'PJM' | 'PL' | 'SPP': Market region the run was submitted for.
    - `scenario` string: Scenario name (e.g. Central, High, Low, Backtest).
    - `simulation_config` object: The exact simulation_config payload submitted at run creation.
    - `status` 'draft' | 'processing' | 'ready_for_review' | 'failed': Current status of the run. Poll GET /runs/{id}/ until `ready_for_review`, then call GET /runs/{id}/results/{resolution}/ to retrieve results.

## Other responses

- `401`: Missing or invalid X-token.

---

[API](https://skmtc.dev/modoenergy/apis/modo-energy-forecasts-api.md) - [All operations](https://skmtc.dev/modoenergy/apis/modo-energy-forecasts-api/llms.txt) - [OpenAPI document](https://skmtc.dev/modoenergy/apis/modo-energy-forecasts-api/revisions/24a95c4b710c?raw)