> For the complete documentation index, see [llms.txt](https://docs.jua.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jua.ai/api-v2/query-engine/open-api-reference/power-forecast.md).

# Power Forecast

Query power generation forecast data for renewable energy sources (Solar, Wind, etc.).

## Query power forecast data

> Query power forecast prediction data for renewable energy generation (Solar, Wind, etc.)\
> and electricity demand (Load).\
> \
> \*\*Dimensions:\*\*\
> \- \`zone\_key\`: Country/region code (e.g. "DE")\
> \- \`psr\_type\`: Generation source type (e.g. "Solar", "Wind Onshore") or "Load" for\
>   electricity demand. Load is currently available for Germany ("DE") only.\
> \
> \*\*Query Modes (mutually exclusive):\*\*\
> \
> 1\. \*\*Horizon mode\*\* (init\_time-centric):\
>    \- \`init\_time\`: Specific init time(s) or relative tokens (\`latest\`, \`latest-N\`)\
>    \- \`max\_prediction\_timedelta\`: Limit forecast horizon (minutes)\
> \
> 2\. \*\*Time range mode\*\* (time-centric):\
>    \- \`start\_time\` / \`end\_time\`: Filter by computed forecast time\
> \
> \*\*Model version and regime:\*\*\
> \- Omit \`\`version\`\` (or \`\`version: "stable"\`\`) to follow the packaged stable pointer —\
>   this \*\*moves\*\* when Jua promotes a new checkpoint.\
> \- \`\`regime\`\` selects which product those aliases resolve against.\
>   \`\`curtailed\`\` (default) is actual production. \`\`uncurtailed\`\` is potential.\
>   A concrete run id ignores \`\`regime\`\`.\
> \- To \*\*freeze\*\* today's stable (safe across promotes): call\
>   \`\`GET /versions\`\`, take the row with \`\`is\_stable: true\`\` (curtailed) or\
>   \`\`is\_stable\_uncurtailed: true\`\`, then pass that run id as \`\`version\`\`.\
> \- \`\`version: "latest"\`\` follows the packaged latest pointer for \`\`regime\`\`.\
> \- \`\`version\_pins\`\` overrides specific (zone, psr) cells in one request.\
> \
> \*\*Response Formats:\*\*\
> \- \`json\`: Columnar JSON format \`{column: \[values], ...}\`\
> \- \`arrow\`: Apache Arrow IPC stream for efficient processing\
> \
> \*\*Authentication\*\*: Requires API key.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"servers":[{"url":"https://query.jua.ai","description":"Production"}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/power-forecast/data":{"post":{"tags":["power-forecast"],"summary":"Query power forecast data","description":"Query power forecast prediction data for renewable energy generation (Solar, Wind, etc.)\nand electricity demand (Load).\n\n**Dimensions:**\n- `zone_key`: Country/region code (e.g. \"DE\")\n- `psr_type`: Generation source type (e.g. \"Solar\", \"Wind Onshore\") or \"Load\" for\n  electricity demand. Load is currently available for Germany (\"DE\") only.\n\n**Query Modes (mutually exclusive):**\n\n1. **Horizon mode** (init_time-centric):\n   - `init_time`: Specific init time(s) or relative tokens (`latest`, `latest-N`)\n   - `max_prediction_timedelta`: Limit forecast horizon (minutes)\n\n2. **Time range mode** (time-centric):\n   - `start_time` / `end_time`: Filter by computed forecast time\n\n**Model version and regime:**\n- Omit ``version`` (or ``version: \"stable\"``) to follow the packaged stable pointer —\n  this **moves** when Jua promotes a new checkpoint.\n- ``regime`` selects which product those aliases resolve against.\n  ``curtailed`` (default) is actual production. ``uncurtailed`` is potential.\n  A concrete run id ignores ``regime``.\n- To **freeze** today's stable (safe across promotes): call\n  ``GET /versions``, take the row with ``is_stable: true`` (curtailed) or\n  ``is_stable_uncurtailed: true``, then pass that run id as ``version``.\n- ``version: \"latest\"`` follows the packaged latest pointer for ``regime``.\n- ``version_pins`` overrides specific (zone, psr) cells in one request.\n\n**Response Formats:**\n- `json`: Columnar JSON format `{column: [values], ...}`\n- `arrow`: Apache Arrow IPC stream for efficient processing\n\n**Authentication**: Requires API key.","operationId":"post_power_forecast_data_v1_power_forecast_data_post","parameters":[{"name":"format","in":"query","required":false,"schema":{"enum":["json","arrow"],"type":"string","description":"Response format: 'json' or 'arrow'","default":"json","title":"Format"},"description":"Response format: 'json' or 'arrow'"},{"name":"include_units","in":"query","required":false,"schema":{"type":"boolean","description":"When true, JSON responses are wrapped in {data, units}. Units are always sent via X-Variable-Units header regardless.","default":false,"title":"Include Units"},"description":"When true, JSON responses are wrapped in {data, units}. Units are always sent via X-Variable-Units header regardless."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowerForecastQuery"}}}},"responses":{"200":{"description":"Successfully retrieved power forecast data","content":{"application/json":{"schema":{}},"application/vnd.apache.arrow.stream":{"description":"Apache Arrow IPC stream format"}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"PowerForecastQuery":{"properties":{"zone_keys":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Zone Keys","description":"List of zone codes (e.g. ['DE', 'FR'])"},"psr_types":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Psr Types","description":"List of PSR types (e.g. ['Solar', 'Wind Onshore'])"},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Default model version for all (zone, psr) cells: 'stable' (default), 'latest', or a run id from GET /versions. Overridden per cell by version_pins. Aliases resolve against ``regime``."},"regime":{"type":"string","enum":["curtailed","uncurtailed"],"title":"Regime","description":"Which packaged product ``version`` aliases resolve against. 'curtailed' (default) is actual production. 'uncurtailed' is potential. A concrete run id ignores this.","default":"curtailed"},"version_pins":{"anyOf":[{"items":{"$ref":"#/components/schemas/VersionPin"},"type":"array"},{"type":"null"}],"title":"Version Pins","description":"Per-(zone_key, psr_type) version overrides. Unlisted cells use ``version``. Each pin may be 'stable', 'latest', or a run id. Example: keep the portfolio on stable but pin DE Solar to a specific checkpoint."},"init_time":{"anyOf":[{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"},{"type":"string","format":"date-time"},{"items":{"anyOf":[{"type":"string","format":"date-time"},{"type":"integer","minimum":0,"description":"Offset from latest forecast (0 = latest, 1 = second latest, etc.)"}]},"type":"array"},{"type":"null"}],"title":"Init Time","description":"Init time selection for horizon mode. Accepts datetime(s), 'latest', or 'latest-N'."},"max_prediction_timedelta":{"anyOf":[{"type":"integer","maximum":18446744073709552000,"minimum":0},{"type":"null"}],"title":"Max Prediction Timedelta","description":"Maximum prediction horizon in minutes (horizon mode)"},"start_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Time","description":"Start of time range (inclusive, time range mode)"},"end_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Time","description":"End of time range (exclusive, time range mode)"},"aggregation_period":{"anyOf":[{"type":"string","enum":["native","hourly","daily","weekly"]},{"type":"null"}],"title":"Aggregation Period","description":"Temporal aggregation for returned rows. ``None`` and ``native`` return raw 15-minute rows; ``hourly``/``daily``/``weekly`` average ``value`` within buckets. ``init_time`` stays a group key so multi-run comparisons remain separated."},"time_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Zone","description":"IANA time zone name for time formatting (e.g. 'Europe/Berlin'). When ``aggregation_period`` is ``daily`` or ``weekly``, also sets the bucket boundary timezone (hourly aggregation ignores this)."},"order_by":{"anyOf":[{"items":{"$ref":"#/components/schemas/OrderByItem_str_"},"type":"array"},{"type":"null"}],"title":"Order By","description":"Columns to order by. Supports direction suffix: 'time__desc' for descending. Default: time ASC."},"pagination":{"anyOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"null"}],"description":"Pagination parameters"},"debias":{"type":"boolean","title":"Debias","description":"Apply leakage-safe walk-forward additive MW debias. Wind uses an eight-week fitting window, solar uses four weeks, and both retain a seven-day exclusion gap. Opt in explicitly; raw predictions remain the API default.","default":false}},"type":"object","title":"PowerForecastQuery","description":"Query parameters for power forecast data.\n\nSupports two mutually exclusive query modes:\n\n**Horizon mode** (init_time-centric):\n    - Specify init_time as datetime(s) or relative tokens (latest/latest-N)\n    - Optionally limit by max_prediction_timedelta\n\n**Time range mode** (time-centric):\n    - Specify start_time / end_time\n    - Computed time = init_time + prediction_timedelta * 60s\n\nCommon filters:\n    - zone_keys: List of zone codes (e.g. [\"DE\", \"FR\"])\n    - psr_types: List of generation types (e.g. [\"Solar\", \"Wind Onshore\"])\n\nVersion selection:\n    - ``version`` is the default for every (zone, psr) cell\n    - ``regime`` selects which packaged product those aliases resolve\n      against (``curtailed`` = actual production, default; ``uncurtailed``\n      = potential). A concrete run id ignores ``regime``.\n    - ``version_pins`` overrides specific cells so one request can mix\n      e.g. DE Solar pinned + FR Wind on stable"},"VersionPin":{"properties":{"zone_key":{"type":"string","title":"Zone Key","description":"Zone code (e.g. 'DE')"},"psr_type":{"type":"string","title":"Psr Type","description":"PSR type (e.g. 'Solar')"},"version":{"type":"string","minLength":1,"title":"Version","description":"stable | latest | run id"},"regime":{"anyOf":[{"type":"string","enum":["curtailed","uncurtailed"]},{"type":"null"}],"title":"Regime","description":"Alias map for this pin when version is stable/latest. None inherits the request regime. Ignored for a concrete run id."}},"type":"object","required":["zone_key","psr_type","version"],"title":"VersionPin","description":"Per-(zone, psr) version override.\n\n``version`` accepts the same values as ``PowerForecastQuery.version``:\n``stable``, ``latest``, or a concrete run id from ``GET /versions``.\n\n``regime`` selects which packaged alias map ``stable`` / ``latest``\nresolve against for this cell. ``None`` inherits the request regime.\nA concrete run id ignores ``regime``."},"OrderByItem_str_":{"properties":{"field":{"type":"string","title":"Field","description":"Field to sort by"},"direction":{"$ref":"#/components/schemas/SortDirection","description":"Sort direction: 'asc' (default) or 'desc'","default":"asc"},"aggregation":{"anyOf":[{"type":"string","enum":["avg","std","min","max","sum","count","median","quantile","argmin","argmax"]},{"type":"null"}],"title":"Aggregation","description":"Aggregation function when ordering by variable"}},"type":"object","required":["field"],"title":"OrderByItem[str]"},"SortDirection":{"type":"string","enum":["asc","desc"],"title":"SortDirection","description":"Sort direction for ORDER BY clauses."},"Pagination":{"properties":{"limit":{"type":"integer","minimum":0,"title":"Limit","default":100},"offset":{"type":"integer","minimum":0,"title":"Offset","default":0}},"type":"object","title":"Pagination"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List available power forecast zones

> Get a list of available zone codes that have power forecast data.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"servers":[{"url":"https://query.jua.ai","description":"Production"}],"paths":{"/v1/power-forecast/zones":{"get":{"tags":["power-forecast"],"summary":"List available power forecast zones","description":"Get a list of available zone codes that have power forecast data.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_power_forecast_zones_v1_power_forecast_zones_get","responses":{"200":{"description":"Successfully retrieved zone list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableZonesResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AvailableZonesResult":{"properties":{"zones":{"items":{"type":"string"},"type":"array","title":"Zones"}},"type":"object","required":["zones"],"title":"AvailableZonesResult","description":"Result for available zones query."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List available PSR types

> Get a list of available PSR (Production Source) types for power forecasts.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"servers":[{"url":"https://query.jua.ai","description":"Production"}],"paths":{"/v1/power-forecast/psr-types":{"get":{"tags":["power-forecast"],"summary":"List available PSR types","description":"Get a list of available PSR (Production Source) types for power forecasts.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_power_forecast_psr_types_v1_power_forecast_psr_types_get","parameters":[{"name":"zone_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional zone key(s) to filter PSR types by","title":"Zone Key"},"description":"Optional zone key(s) to filter PSR types by"},{"name":"strict","in":"query","required":false,"schema":{"type":"boolean","description":"When true, return only PSR types produced in *every* given zone (intersection). Default returns the union across zones.","default":false,"title":"Strict"},"description":"When true, return only PSR types produced in *every* given zone (intersection). Default returns the union across zones."}],"responses":{"200":{"description":"Successfully retrieved PSR type list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailablePsrTypesResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AvailablePsrTypesResult":{"properties":{"psr_types":{"items":{"type":"string"},"type":"array","title":"Psr Types"}},"type":"object","required":["psr_types"],"title":"AvailablePsrTypesResult","description":"Result for available PSR types query."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List available model versions

> Catalog of pin-able run ids per zone/PSR.\
> \
> \`\`description\`\` is packaged metadata for a known run id. Historical versions\
> without retained metadata return \`\`null\`\`.\
> \
> \*\*Freeze today's stable (recommended for promote-safety):\*\*\
> 1\. Call this endpoint (optionally filter with \`\`zone\_key\`\` / \`\`psr\_type\`\`).\
> 2\. For each cell you care about, take \`\`model\_version\`\` where \`\`is\_stable\`\`\
>    is true.\
> 3\. Pass that run id as \`\`version\`\` on \`\`POST /power-forecast/data\`\` (whole\
>    request) or in \`\`version\_pins\`\` (per cell).\
> \
> \`\`version: "stable"\`\` follows live promotes. A concrete run id does \*\*not\*\*.\
> \
> \`\`is\_latest\`\` marks the curtailed preview alias (\`\`version=latest\`\`).\
> \`\`is\_stable\_uncurtailed\`\` / \`\`is\_latest\_uncurtailed\`\` mark the uncurtailed\
> sibling maps.\
> \
> Requires power-forecast model entitlement (same as \`\`POST /data\`\`): the\
> catalog exposes internal checkpoint / WandB run ids used for pinning.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"servers":[{"url":"https://query.jua.ai","description":"Production"}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/power-forecast/versions":{"get":{"tags":["power-forecast"],"summary":"List available model versions","description":"Catalog of pin-able run ids per zone/PSR.\n\n``description`` is packaged metadata for a known run id. Historical versions\nwithout retained metadata return ``null``.\n\n**Freeze today's stable (recommended for promote-safety):**\n1. Call this endpoint (optionally filter with ``zone_key`` / ``psr_type``).\n2. For each cell you care about, take ``model_version`` where ``is_stable``\n   is true.\n3. Pass that run id as ``version`` on ``POST /power-forecast/data`` (whole\n   request) or in ``version_pins`` (per cell).\n\n``version: \"stable\"`` follows live promotes. A concrete run id does **not**.\n\n``is_latest`` marks the curtailed preview alias (``version=latest``).\n``is_stable_uncurtailed`` / ``is_latest_uncurtailed`` mark the uncurtailed\nsibling maps.\n\nRequires power-forecast model entitlement (same as ``POST /data``): the\ncatalog exposes internal checkpoint / WandB run ids used for pinning.","operationId":"get_power_forecast_versions_v1_power_forecast_versions_get","parameters":[{"name":"zone_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional zone key(s) to filter versions by","title":"Zone Key"},"description":"Optional zone key(s) to filter versions by"},{"name":"psr_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional PSR type(s) to filter versions by","title":"Psr Type"},"description":"Optional PSR type(s) to filter versions by"}],"responses":{"200":{"description":"Successfully retrieved version catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableVersionsResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AvailableVersionsResult":{"properties":{"versions":{"items":{"$ref":"#/components/schemas/VersionInfo"},"type":"array","title":"Versions"}},"type":"object","required":["versions"],"title":"AvailableVersionsResult","description":"Catalog of pin-able model versions, optionally filtered by zone/PSR."},"VersionInfo":{"properties":{"model_version":{"type":"string","title":"Model Version"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable metadata packaged with the run id, when known."},"zone_key":{"type":"string","title":"Zone Key"},"psr_type":{"type":"string","title":"Psr Type"},"is_stable":{"type":"boolean","title":"Is Stable","default":false},"is_latest":{"type":"boolean","title":"Is Latest","default":false},"is_stable_uncurtailed":{"type":"boolean","title":"Is Stable Uncurtailed","default":false},"is_latest_uncurtailed":{"type":"boolean","title":"Is Latest Uncurtailed","default":false},"earliest_init_time":{"type":"string","format":"date-time","title":"Earliest Init Time"},"latest_init_time":{"type":"string","format":"date-time","title":"Latest Init Time"}},"type":"object","required":["model_version","zone_key","psr_type","earliest_init_time","latest_init_time"],"title":"VersionInfo","description":"One model_version available for a (zone_key, psr_type) cell."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## Check if latest forecast uses fallback initial conditions

> Check whether the most recent power forecast was generated using fallback\
> initial conditions (i.e. ENTSO-E source data was unavailable).\
> \
> Returns \`{"is\_fallback": true}\` when the latest forecast used synthetic\
> history, and \`{"is\_fallback": false}\` otherwise.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"servers":[{"url":"https://query.jua.ai","description":"Production"}],"paths":{"/v1/power-forecast/fallback-status":{"get":{"tags":["power-forecast"],"summary":"Check if latest forecast uses fallback initial conditions","description":"Check whether the most recent power forecast was generated using fallback\ninitial conditions (i.e. ENTSO-E source data was unavailable).\n\nReturns `{\"is_fallback\": true}` when the latest forecast used synthetic\nhistory, and `{\"is_fallback\": false}` otherwise.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_fallback_status_v1_power_forecast_fallback_status_get","parameters":[{"name":"zone_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional zone key to check (e.g. 'DE'). If omitted, checks across all zones.","title":"Zone Key"},"description":"Optional zone key to check (e.g. 'DE'). If omitted, checks across all zones."}],"responses":{"200":{"description":"Fallback status","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List init times that used fallback initial conditions

> Return init times whose forecasts were generated with fallback (estimated)\
> initial conditions.  The frontend uses this to flag specific model runs\
> in the chart legend as potentially degraded.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"servers":[{"url":"https://query.jua.ai","description":"Production"}],"paths":{"/v1/power-forecast/fallback-init-times":{"get":{"tags":["power-forecast"],"summary":"List init times that used fallback initial conditions","description":"Return init times whose forecasts were generated with fallback (estimated)\ninitial conditions.  The frontend uses this to flag specific model runs\nin the chart legend as potentially degraded.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_fallback_init_times_v1_power_forecast_fallback_init_times_get","parameters":[{"name":"zone_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional zone key to filter by (e.g. 'DE'). If omitted, returns fallback init times across all zones.","title":"Zone Key"},"description":"Optional zone key to filter by (e.g. 'DE'). If omitted, returns fallback init times across all zones."}],"responses":{"200":{"description":"List of fallback init times","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## List available init times

> Get available forecast init times with their max prediction horizon.\
> \
> Used by the dashboard to populate the init\_time dropdown when creating a\
> power forecast data source.  Results are ordered newest-first.\
> \
> When \`include\_availability=true\` is passed along with zone\_key and psr\_type\
> filters, the response includes an \`availability\_by\_init\_time\` field that\
> maps each init\_time to the list of (zone\_key, psr\_type) combinations that\
> are available for it. This allows determining which specific combinations\
> are missing for excluded init times without additional API calls.\
> \
> This is a metadata endpoint and does not require authentication.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"servers":[{"url":"https://query.jua.ai","description":"Production"}],"paths":{"/v1/power-forecast/init-times":{"get":{"tags":["power-forecast"],"summary":"List available init times","description":"Get available forecast init times with their max prediction horizon.\n\nUsed by the dashboard to populate the init_time dropdown when creating a\npower forecast data source.  Results are ordered newest-first.\n\nWhen `include_availability=true` is passed along with zone_key and psr_type\nfilters, the response includes an `availability_by_init_time` field that\nmaps each init_time to the list of (zone_key, psr_type) combinations that\nare available for it. This allows determining which specific combinations\nare missing for excluded init times without additional API calls.\n\nThis is a metadata endpoint and does not require authentication.","operationId":"get_power_forecast_init_times_v1_power_forecast_init_times_get","parameters":[{"name":"zone_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Zone key(s) to filter init times by","title":"Zone Key"},"description":"Zone key(s) to filter init times by"},{"name":"psr_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"PSR type(s) to filter by. When multiple are given, only init_times available for ALL of them are returned.","title":"Psr Type"},"description":"PSR type(s) to filter by. When multiple are given, only init_times available for ALL of them are returned."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of init times to return. Ignored only when BOTH start_time and end_time are provided (the closed window then bounds the listing instead of the row count). With a single bound the limit still applies, since the other side is open.","default":192,"title":"Limit"},"description":"Maximum number of init times to return. Ignored only when BOTH start_time and end_time are provided (the closed window then bounds the listing instead of the row count). With a single bound the limit still applies, since the other side is open."},{"name":"order","in":"query","required":false,"schema":{"enum":["desc","asc"],"type":"string","description":"Sort direction for init_time: 'desc' (newest first, default) or 'asc' (oldest first)","default":"desc","title":"Order"},"description":"Sort direction for init_time: 'desc' (newest first, default) or 'asc' (oldest first)"},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Inclusive lower bound on init_time (ISO-8601, UTC). When set together with end_time, all init_times in the closed window are returned regardless of the limit/1000 row cap; on its own the limit still applies.","title":"Start Time"},"description":"Inclusive lower bound on init_time (ISO-8601, UTC). When set together with end_time, all init_times in the closed window are returned regardless of the limit/1000 row cap; on its own the limit still applies."},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Exclusive upper bound on init_time (ISO-8601, UTC): init_time < end_time. On its own the limit still applies (the lower side is unbounded).","title":"End Time"},"description":"Exclusive upper bound on init_time (ISO-8601, UTC): init_time < end_time. On its own the limit still applies (the lower side is unbounded)."},{"name":"include_availability","in":"query","required":false,"schema":{"type":"boolean","description":"When true and zone_key/psr_type are provided, include per-init-time availability breakdown showing which zone/PSR combinations are available for each init_time.","default":false,"title":"Include Availability"},"description":"When true and zone_key/psr_type are provided, include per-init-time availability breakdown showing which zone/PSR combinations are available for each init_time."},{"name":"version","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Model version: 'stable' (default), 'latest', or a run id from GET /versions. Same semantics as POST /data.","title":"Version"},"description":"Model version: 'stable' (default), 'latest', or a run id from GET /versions. Same semantics as POST /data."},{"name":"regime","in":"query","required":false,"schema":{"enum":["curtailed","uncurtailed"],"type":"string","description":"Product map version aliases resolve against. 'curtailed' (default) is actual production. 'uncurtailed' is potential. Same semantics as POST /data.","default":"curtailed","title":"Regime"},"description":"Product map version aliases resolve against. 'curtailed' (default) is actual production. 'uncurtailed' is potential. Same semantics as POST /data."}],"responses":{"200":{"description":"Successfully retrieved init times","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableInitTimesResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AvailableInitTimesResult":{"properties":{"init_times":{"items":{"$ref":"#/components/schemas/InitTimeInfo"},"type":"array","title":"Init Times"},"total_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Count"},"archive_earliest_init_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Archive Earliest Init Time"},"archive_latest_init_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Archive Latest Init Time"},"availability_by_init_time":{"anyOf":[{"additionalProperties":{"items":{"prefixItems":[{"type":"string"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array"},"type":"object"},{"type":"null"}],"title":"Availability By Init Time"}},"type":"object","required":["init_times"],"title":"AvailableInitTimesResult","description":"Result for available init times query."},"InitTimeInfo":{"properties":{"init_time":{"type":"string","format":"date-time","title":"Init Time"},"max_prediction_timedelta":{"type":"integer","title":"Max Prediction Timedelta"}},"type":"object","required":["init_time","max_prediction_timedelta"],"title":"InitTimeInfo","description":"Information about an available init_time.\n\n``model_version`` / ``completed_at`` are internal catalogue fields (v2\nruns / X-As-Of). They stay off the v1 ``/init-times`` wire via\n``exclude=True``."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## Power forecast dissemination delay metrics

> Per-(zone, psr\_type, init\_time) dissemination delay relative to ZONE\_SCHEDULES publication time (completed\_at - (init\_time + entsoe\_lag + inference\_overhead)). Used by admin-panel monitoring.

```json
{"openapi":"3.1.0","info":{"title":"Jua Query Engine API","version":"0.1.0"},"tags":[{"name":"power-forecast","description":"Query power generation forecast data for renewable energy sources (Solar, Wind, etc.)."}],"servers":[{"url":"https://query.jua.ai","description":"Production"}],"security":[{"HTTPBearer":[]}],"paths":{"/v1/power-forecast/dissemination-metrics":{"get":{"tags":["power-forecast"],"summary":"Power forecast dissemination delay metrics","description":"Per-(zone, psr_type, init_time) dissemination delay relative to ZONE_SCHEDULES publication time (completed_at - (init_time + entsoe_lag + inference_overhead)). Used by admin-panel monitoring.","operationId":"get_power_forecast_dissemination_metrics_v1_power_forecast_dissemination_metrics_get","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only include init_times on/after this datetime","title":"Since"},"description":"Only include init_times on/after this datetime"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only include init_times before this datetime","title":"Until"},"description":"Only include init_times before this datetime"},{"name":"zone_keys","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional zone filter (defaults to ZONE_SCHEDULES)","title":"Zone Keys"},"description":"Optional zone filter (defaults to ZONE_SCHEDULES)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowerDisseminationMetricsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"PowerDisseminationMetricsResponse":{"properties":{"since":{"type":"string","format":"date-time","title":"Since"},"until":{"type":"string","format":"date-time","title":"Until"},"metrics_per_zone":{"items":{"$ref":"#/components/schemas/PowerZoneMetrics"},"type":"array","title":"Metrics Per Zone"},"fleet_on_time_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fleet On Time Pct"},"worst_zone_p95_min":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Worst Zone P95 Min"},"worst_zone_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Worst Zone Key"},"missing_runs":{"type":"integer","title":"Missing Runs","description":"Sum of ``missing_count`` across all zone/psr pairs","default":0},"fallback_runs":{"type":"integer","title":"Fallback Runs","description":"Sum of ``fallback_count`` across all zone/psr pairs","default":0}},"type":"object","required":["since","until","metrics_per_zone"],"title":"PowerDisseminationMetricsResponse"},"PowerZoneMetrics":{"properties":{"zone_key":{"type":"string","title":"Zone Key"},"psr_type":{"type":"string","title":"Psr Type"},"sample_count":{"type":"integer","title":"Sample Count"},"on_time_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"On Time Pct"},"mean_delay_min":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean Delay Min"},"p95_delay_min":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Delay Min"},"missing_count":{"type":"integer","title":"Missing Count","description":"Init_time slots expected from the inferred cadence but never run. Zero when the window holds fewer than three runs (cadence is not inferable).","default":0},"cadence_minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cadence Minutes","description":"Modal gap between consecutive init_times, i.e. the cadence the missing slots were derived from. Null when not inferable."},"missing_init_times":{"items":{"type":"string","format":"date-time"},"type":"array","title":"Missing Init Times","description":"The expected-but-absent init_times behind ``missing_count``, ascending, truncated to the most recent 200."},"fallback_count":{"type":"integer","title":"Fallback Count","description":"Runs whose latest write used forecast-IC fallback initial conditions (``step_status.forecast_ic``), i.e. TSO actuals were not available in time. Provisional: overwritten once real actuals arrive.","default":0},"fallback_init_times":{"items":{"type":"string","format":"date-time"},"type":"array","title":"Fallback Init Times","description":"The init_times behind ``fallback_count``, ascending, truncated to the most recent 200."},"daily_delay_buckets":{"items":{"$ref":"#/components/schemas/PowerZoneDelayBucket"},"type":"array","title":"Daily Delay Buckets"}},"type":"object","required":["zone_key","psr_type","sample_count"],"title":"PowerZoneMetrics"},"PowerZoneDelayBucket":{"properties":{"date":{"type":"string","title":"Date","description":"UTC date (YYYY-MM-DD) of the init_time"},"count":{"type":"integer","title":"Count"},"mean":{"type":"number","title":"Mean"},"p50":{"type":"number","title":"P50"},"p95":{"type":"number","title":"P95"},"on_time":{"type":"integer","title":"On Time"},"yellow":{"type":"integer","title":"Yellow"},"red":{"type":"integer","title":"Red"},"missing":{"type":"integer","title":"Missing","description":"Expected-but-absent init_time slots on this date","default":0}},"type":"object","required":["date","count","mean","p50","p95","on_time","yellow","red"],"title":"PowerZoneDelayBucket"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.jua.ai/api-v2/query-engine/open-api-reference/power-forecast.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.