{ "openapi": "3.1.0", "info": { "title": "Telescope API", "version": "2.0.0", "description": "Supported customer and provider workflows." }, "servers": [ { "url": "https://telescope.energy" } ], "paths": { "/api/v2/public/products/{slug}/performance": { "get": { "operationId": "performance", "tags": [ "public" ], "summary": "Read public forecast performance", "description": "Returns forecast accuracy for 1, 7 or 30 completed local days, or one selected date. Price and quantity forecasts use P50 mean absolute error (MAE); probability forecasts use the Brier score.\n\nThe headline uses forecasts published strictly before market gate closure, or five minutes before delivery for rolling products.\n\nAt least 50% of expected intervals must be matched; sparsely observed series require at least 30 matches.\n\nDirections are evaluated separately. Period scores aggregate observation errors, not unweighted daily averages. Missing metrics are not zero.\n\nFixed periods end yesterday in the product time zone. For a specific date, use period=date and day; the availability endpoint lists eligible dates.\n\nOnly intervals whose decision cutoff has passed are scored. Provisional actuals are included, and revised actuals may change results. Responses can be cached for up to 60 seconds.\n\nUnknown or unsupported products return 404.", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource identifier returned by the catalog or list endpoint.", "schema": { "type": "string" } }, { "name": "variant", "in": "query", "required": false, "description": "Case-sensitive resource identifier.", "schema": { "type": "string", "pattern": "\\S", "description": "Case-sensitive resource identifier." } }, { "name": "series", "in": "query", "required": false, "description": "Case-sensitive resource identifier.", "schema": { "type": "string", "pattern": "\\S", "description": "Case-sensitive resource identifier." } }, { "name": "period", "in": "query", "required": false, "description": "Defaults to 30.", "schema": { "default": "30", "type": "string", "enum": [ "1", "7", "30", "date" ] } }, { "name": "day", "in": "query", "required": false, "description": "Required only for period=date; within the 90-day history and product horizon. Current and future delivery days require actuals; use the availability endpoint for selectable dates.", "schema": { "description": "Required only for period=date; within the 90-day history and product horizon. Current and future delivery days require actuals; use the availability endpoint for selectable dates.", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "performance": { "type": "object", "properties": { "slug": { "type": "string" }, "variantKey": { "type": "string" }, "seriesKey": { "type": "string" }, "timezone": { "type": "string" }, "metric": { "type": "string", "enum": [ "mae", "brier" ] }, "unit": { "type": "string" }, "fromDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "toDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "historyFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "lastDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "computedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, { "type": "null" } ] }, "updating": { "type": "boolean" }, "headline": { "anyOf": [ { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "available", "insufficient_data", "pending", "failed", "unavailable" ] }, "count": { "type": "number", "description": "Matched forecast and actual pairs used for scoring." }, "expected": { "type": "number", "description": "Coverage denominator: grid intervals for continuous actuals, observed intervals for sparse actuals." }, "actualCount": { "type": "number", "description": "Intervals with actual values." }, "coverage": { "type": "number", "description": "Matched pairs divided by expected intervals." }, "scoredDays": { "type": "number" }, "totalDays": { "type": "number" }, "provisional": { "type": "boolean" }, "sparse": { "type": "boolean", "description": "The actual series is sparse and requires a minimum observation count." }, "key": { "type": "string" }, "leadMinutes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "value", "status", "count", "expected", "actualCount", "coverage", "scoredDays", "totalDays", "provisional", "sparse", "key", "leadMinutes" ], "additionalProperties": false }, { "type": "null" } ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "available", "insufficient_data", "pending", "failed", "unavailable" ] }, "count": { "type": "number", "description": "Matched forecast and actual pairs used for scoring." }, "expected": { "type": "number", "description": "Coverage denominator: grid intervals for continuous actuals, observed intervals for sparse actuals." }, "actualCount": { "type": "number", "description": "Intervals with actual values." }, "coverage": { "type": "number", "description": "Matched pairs divided by expected intervals." }, "scoredDays": { "type": "number" }, "totalDays": { "type": "number" }, "provisional": { "type": "boolean" }, "sparse": { "type": "boolean", "description": "The actual series is sparse and requires a minimum observation count." }, "key": { "type": "string" }, "leadMinutes": { "type": "number" } }, "required": [ "value", "status", "count", "expected", "actualCount", "coverage", "scoredDays", "totalDays", "provisional", "sparse", "key", "leadMinutes" ], "additionalProperties": false } } }, "required": [ "slug", "variantKey", "seriesKey", "timezone", "metric", "unit", "fromDay", "toDay", "historyFrom", "lastDay", "computedAt", "headline", "points" ], "additionalProperties": false } }, "required": [ "performance" ], "additionalProperties": false }, "example": { "performance": { "slug": "balancing-price-de", "variantKey": "forecast", "seriesKey": "signed", "timezone": "Europe/Berlin", "metric": "mae", "unit": "EUR_MWH", "fromDay": "2026-08-01", "toDay": "2026-08-30", "historyFrom": "2026-06-02", "lastDay": "2026-08-30", "computedAt": "2026-08-31T00:00:00.000Z", "updating": false, "headline": { "value": 8.4, "status": "available", "count": 2880, "expected": 2880, "actualCount": 2880, "coverage": 1, "scoredDays": 30, "totalDays": 30, "provisional": true, "sparse": false, "key": "lead:5", "leadMinutes": 5 }, "points": [] } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/public/products/{slug}/performance/lead-times": { "get": { "operationId": "performance-lead-times", "tags": [ "public" ], "summary": "Read error by lead time", "description": "Compares forecast accuracy at the available minimum decision leads over the last 30 completed local delivery days.\n\nEach lead requires at least 25% coverage over the full 30-day period and matches on at least 7 distinct delivery days. Sparse series also require at least 30 matches. Directions are evaluated separately; scores aggregate observation errors.\n\nFor gate-closure products, selection is also capped at the market gate. The selected forecast may be older than the requested minimum lead.\n\nProvisional actuals may contribute. Treat missing scores as unavailable, not zero.\n\nResponses can be cached for up to 60 seconds. Unknown or unsupported products return 404.", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource identifier returned by the catalog or list endpoint.", "schema": { "type": "string" } }, { "name": "variant", "in": "query", "required": false, "description": "Case-sensitive resource identifier.", "schema": { "type": "string", "pattern": "\\S", "description": "Case-sensitive resource identifier." } }, { "name": "series", "in": "query", "required": false, "description": "Case-sensitive resource identifier.", "schema": { "type": "string", "pattern": "\\S", "description": "Case-sensitive resource identifier." } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "performance": { "type": "object", "properties": { "slug": { "type": "string" }, "variantKey": { "type": "string" }, "seriesKey": { "type": "string" }, "timezone": { "type": "string" }, "metric": { "type": "string", "enum": [ "mae", "brier" ] }, "unit": { "type": "string" }, "fromDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "toDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "historyFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "lastDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "computedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, { "type": "null" } ] }, "updating": { "type": "boolean" }, "headline": { "anyOf": [ { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "available", "insufficient_data", "pending", "failed", "unavailable" ] }, "count": { "type": "number", "description": "Matched forecast and actual pairs used for scoring." }, "expected": { "type": "number", "description": "Coverage denominator: grid intervals for continuous actuals, observed intervals for sparse actuals." }, "actualCount": { "type": "number", "description": "Intervals with actual values." }, "coverage": { "type": "number", "description": "Matched pairs divided by expected intervals." }, "scoredDays": { "type": "number" }, "totalDays": { "type": "number" }, "provisional": { "type": "boolean" }, "sparse": { "type": "boolean", "description": "The actual series is sparse and requires a minimum observation count." }, "key": { "type": "string" }, "leadMinutes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "value", "status", "count", "expected", "actualCount", "coverage", "scoredDays", "totalDays", "provisional", "sparse", "key", "leadMinutes" ], "additionalProperties": false }, { "type": "null" } ] }, "points": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "available", "insufficient_data", "pending", "failed", "unavailable" ] }, "count": { "type": "number", "description": "Matched forecast and actual pairs used for scoring." }, "expected": { "type": "number", "description": "Coverage denominator: grid intervals for continuous actuals, observed intervals for sparse actuals." }, "actualCount": { "type": "number", "description": "Intervals with actual values." }, "coverage": { "type": "number", "description": "Matched pairs divided by expected intervals." }, "scoredDays": { "type": "number" }, "totalDays": { "type": "number" }, "provisional": { "type": "boolean" }, "sparse": { "type": "boolean", "description": "The actual series is sparse and requires a minimum observation count." }, "key": { "type": "string" }, "leadMinutes": { "type": "number" } }, "required": [ "value", "status", "count", "expected", "actualCount", "coverage", "scoredDays", "totalDays", "provisional", "sparse", "key", "leadMinutes" ], "additionalProperties": false } } }, "required": [ "slug", "variantKey", "seriesKey", "timezone", "metric", "unit", "fromDay", "toDay", "historyFrom", "lastDay", "computedAt", "headline", "points" ], "additionalProperties": false } }, "required": [ "performance" ], "additionalProperties": false }, "example": { "performance": { "slug": "balancing-price-de", "variantKey": "forecast", "seriesKey": "signed", "timezone": "Europe/Berlin", "metric": "mae", "unit": "EUR_MWH", "fromDay": "2026-08-01", "toDay": "2026-08-30", "historyFrom": "2026-06-02", "lastDay": "2026-08-30", "computedAt": "2026-08-31T00:00:00.000Z", "updating": false, "headline": null, "points": [ { "value": 8.4, "status": "available", "count": 2880, "expected": 2880, "actualCount": 2880, "coverage": 1, "scoredDays": 30, "totalDays": 30, "provisional": true, "sparse": false, "key": "lead:5", "leadMinutes": 5 } ] } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/public/products/{slug}/performance/availability": { "get": { "operationId": "performance-availability", "tags": [ "public" ], "summary": "Read available performance dates", "description": "Lists local dates with an available headline accuracy score for the selected product variant and series.\n\nIncludes up to 90 days of history, plus today and future delivery dates within the product horizon when qualifying actuals and elapsed decision cutoffs exist.\n\nUses the headline decision time and coverage thresholds; provisional actuals qualify.\n\nResponses can be cached for up to 60 seconds and expire at local midnight. An unknown series returns 422; an unavailable product returns 404.", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource identifier returned by the catalog or list endpoint.", "schema": { "type": "string" } }, { "name": "variant", "in": "query", "required": false, "description": "Case-sensitive resource identifier.", "schema": { "type": "string", "pattern": "\\S", "description": "Case-sensitive resource identifier." } }, { "name": "series", "in": "query", "required": false, "description": "Case-sensitive resource identifier.", "schema": { "type": "string", "pattern": "\\S", "description": "Case-sensitive resource identifier." } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "availability": { "type": "object", "properties": { "slug": { "type": "string" }, "variantKey": { "type": "string" }, "seriesKey": { "type": "string" }, "timezone": { "type": "string" }, "historyFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "lastDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Last completed local day; fixed periods end here." }, "latestAvailableDay": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, { "type": "null" } ], "description": "Latest qualifying delivery day, including today or future days with actuals." }, "availableDays": { "type": "array", "items": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." } } }, "required": [ "slug", "variantKey", "seriesKey", "timezone", "historyFrom", "lastDay", "latestAvailableDay", "availableDays" ], "additionalProperties": false } }, "required": [ "availability" ], "additionalProperties": false }, "example": { "availability": { "slug": "balancing-price-de", "variantKey": "forecast", "seriesKey": "signed", "timezone": "Europe/Berlin", "historyFrom": "2026-06-02", "lastDay": "2026-08-30", "latestAvailableDay": "2026-08-30", "availableDays": [ "2026-08-29", "2026-08-30" ] } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/producer/definitions": { "get": { "operationId": "definitions", "tags": [ "producer" ], "summary": "List allowed forecast definitions", "description": "Lists the forecast definitions available to your provider account. Each definition specifies the required time grid, series, outputs, units and submission policy.\n\nKeys are case-sensitive. Refresh definitions before scheduled submissions.\n\nSee [submission scheduling](/submit-forecasts/scheduling) for rolling coverage and gate-closure deadlines.\n\nAccount rate limit: 120 read requests per minute, with a burst capacity of 30. The token bucket refills continuously and is shared across all API keys of the account and both Customer and Producer read endpoints. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "catalog:read", "parameters": [], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "definitions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "variantLabel": { "type": "string" }, "market": { "type": "string" }, "zone": { "type": "string" }, "target": { "type": "string" }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "timezone": { "type": "string" }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "horizon": { "type": "object", "properties": { "firstDeliveryDayOffset": { "type": "number" }, "maxHorizonDays": { "type": "number" } }, "required": [ "firstDeliveryDayOffset", "maxHorizonDays" ], "additionalProperties": false }, "submissionRules": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "rolling" }, "minimumContinuousHours": { "type": "number" }, "maximumStartAgeMinutes": { "type": "number" }, "mustCoverNextInterval": { "type": "boolean", "const": true }, "allowPartialBoundaryDays": { "type": "boolean", "const": true }, "requireContiguousIntervals": { "type": "boolean", "const": true } }, "required": [ "mode", "minimumContinuousHours", "maximumStartAgeMinutes", "mustCoverNextInterval", "allowPartialBoundaryDays", "requireContiguousIntervals" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "gate_closure" }, "gateDaysBeforeDelivery": { "type": "number" }, "gateLocalTime": { "type": "string" }, "submissionLeadMinutes": { "type": "number" }, "requireCompleteDeliveryDays": { "type": "boolean", "const": true } }, "required": [ "mode", "gateDaysBeforeDelivery", "gateLocalTime", "submissionLeadMinutes", "requireCompleteDeliveryDays" ], "additionalProperties": false } ] } }, "required": [ "key", "title", "market", "zone", "target", "resolution", "timezone", "unit", "outputs", "series", "horizon", "submissionRules" ], "additionalProperties": false } } }, "required": [ "definitions" ], "additionalProperties": false }, "example": { "definitions": [ { "key": "afrr-capacity-price-de", "title": "Automatic Frequency Restoration Reserve (aFRR) ยท DE", "market": "afrr", "zone": "DE", "target": "capacity-price", "resolution": "PT4H", "timezone": "Europe/Berlin", "unit": "EUR_MWH", "outputs": [ { "key": "p10", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.1 }, { "key": "p50", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.5 }, { "key": "p90", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.9 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "horizon": { "firstDeliveryDayOffset": 1, "maxHorizonDays": 7 }, "submissionRules": { "mode": "gate_closure", "gateDaysBeforeDelivery": 1, "gateLocalTime": "09:00", "submissionLeadMinutes": 5, "requireCompleteDeliveryDays": true } } ] } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/producer/submissions": { "post": { "operationId": "create-submission", "tags": [ "producer" ], "summary": "Submit forecast snapshots", "description": "Validates and accepts a complete forecast submission. If any value or delivery window is invalid, the entire submission is rejected and no forecast values are stored.\n\nUse exactly one of outputs or series per timestamp. Multiple configured series require series; include all configured outputs.\n\nUnknown fields, duplicate timestamps, incomplete grids, non-finite values and values outside the configured bounds are rejected. Quantiles must be ordered within each series.\n\nBodies must not exceed 1 MiB (1,048,576 UTF-8 bytes) or 10,000 scalar forecast values across all timestamps, series and outputs. Oversized bodies return 413 SUBMISSION_TOO_LARGE; excess values return 422 TOO_MANY_VALUES or a SUBMISSION_REJECTED issue with that code. generatedAt must not be more than five minutes in the future.\n\nPersist one Idempotency-Key per logical submission. Retry with exactly the same body and key. A changed body with the same key returns 409 IDEMPOTENCY_KEY_CONFLICT.\n\nA validation failure returns 422 SUBMISSION_REJECTED with at most 100 details.issues containing path, code, message and optionally deliveryDay. details.issueCount reports the total; details.issuesTruncated indicates omitted issues. An identical retry returns the same stored issue summary. Correct the payload and use a new key.\n\nAcceptance confirms receipt of your forecast. Customer publication is a separate step.\n\nAccount rate limit: 30 submissions per minute, with a burst capacity of 20. The token bucket refills continuously and is shared across all API keys of the account. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "submissions:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Persist one key per logical submission and reuse it only for identical retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "definition": { "type": "string", "pattern": "\\S", "description": "Definition key returned by the producer catalog." }, "model": { "description": "Registered internal model key; omit for the managed default model.", "type": "string", "pattern": "\\S" }, "generatedAt": { "type": "string", "allOf": [ { "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "pattern": "T\\d{2}:\\d{2}:\\d{2}" } ], "description": "Producer-reported generation time; eligibility uses trusted receipt time." }, "deliveryWindows": { "maxItems": 8192, "type": "array", "items": { "type": "object", "properties": { "deliveryDay": { "type": "string", "description": "Local delivery day; validated against the product contract." }, "values": { "maxItems": 8192, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "validTime": { "type": "string", "allOf": [ { "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "pattern": "T\\d{2}:\\d{2}:\\d{2}" } ], "description": "RFC 3339 timestamp with seconds and Z or an explicit UTC offset." }, "outputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "Every configured output for a single-series definition." } }, "required": [ "validTime", "outputs" ], "additionalProperties": false }, { "type": "object", "properties": { "validTime": { "type": "string", "allOf": [ { "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "pattern": "T\\d{2}:\\d{2}:\\d{2}" } ], "description": "RFC 3339 timestamp with seconds and Z or an explicit UTC offset." }, "series": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "description": "Every configured series, each containing all outputs." } }, "required": [ "validTime", "series" ], "additionalProperties": false } ] } } }, "required": [ "deliveryDay", "values" ], "additionalProperties": false }, "description": "Local-day containers. Product-specific grid, coverage and horizon rules apply." } }, "required": [ "definition", "generatedAt", "deliveryWindows" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "replayed": { "type": "boolean" }, "runId": { "type": "string" }, "definition": { "type": "string" }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "status": { "type": "string", "const": "accepted" }, "deliveryWindows": { "type": "array", "items": { "type": "object", "properties": { "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "expectedTimestamps": { "type": "number", "description": "Interval starts in the complete local delivery day." }, "timestampCount": { "type": "number", "description": "Distinct submitted interval starts in this delivery day." }, "valueCount": { "type": "number", "description": "Numeric values across all submitted timestamps, series and outputs." }, "coverageRatio": { "type": "number", "description": "Submitted timestamps divided by expected timestamps." }, "deadlineAt": { "description": "Exclusive receipt deadline for a gate-closure delivery day.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "deliveryDay", "expectedTimestamps", "timestampCount", "valueCount", "coverageRatio" ], "additionalProperties": false } } }, "required": [ "replayed", "runId", "definition", "receivedAt", "status", "deliveryWindows" ], "additionalProperties": false }, "example": { "replayed": false, "runId": "m57abc123", "status": "accepted", "deliveryWindows": [ { "deliveryDay": "2026-07-27", "expectedTimestamps": 6, "timestampCount": 6, "valueCount": 36, "coverageRatio": 1, "deadlineAt": "2026-07-27T08:45:00.000Z" } ], "definition": "afrr-capacity-price-de", "receivedAt": "2026-07-26T16:01:04.000Z" } } } }, "201": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "replayed": { "type": "boolean" }, "runId": { "type": "string" }, "definition": { "type": "string" }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "status": { "type": "string", "const": "accepted" }, "deliveryWindows": { "type": "array", "items": { "type": "object", "properties": { "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "expectedTimestamps": { "type": "number", "description": "Interval starts in the complete local delivery day." }, "timestampCount": { "type": "number", "description": "Distinct submitted interval starts in this delivery day." }, "valueCount": { "type": "number", "description": "Numeric values across all submitted timestamps, series and outputs." }, "coverageRatio": { "type": "number", "description": "Submitted timestamps divided by expected timestamps." }, "deadlineAt": { "description": "Exclusive receipt deadline for a gate-closure delivery day.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "deliveryDay", "expectedTimestamps", "timestampCount", "valueCount", "coverageRatio" ], "additionalProperties": false } } }, "required": [ "replayed", "runId", "definition", "receivedAt", "status", "deliveryWindows" ], "additionalProperties": false }, "example": { "replayed": false, "runId": "m57abc123", "status": "accepted", "deliveryWindows": [ { "deliveryDay": "2026-07-27", "expectedTimestamps": 6, "timestampCount": 6, "valueCount": 36, "coverageRatio": 1, "deadlineAt": "2026-07-27T08:45:00.000Z" } ], "definition": "afrr-capacity-price-de", "receivedAt": "2026-07-26T16:01:04.000Z" } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "413": { "description": "Submission body exceeds 1 MiB (1,048,576 bytes).", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } }, "get": { "operationId": "list-submissions", "tags": [ "producer" ], "summary": "List your accepted submissions", "description": "Lists your accepted submissions, newest first.\n\nOnly submissions belonging to your provider account are returned.\n\nAccount rate limit: 120 read requests per minute, with a burst capacity of 30. The token bucket refills continuously and is shared across all API keys of the account and both Customer and Producer read endpoints. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "submissions:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum accepted runs per page, newest first. Defaults to 50.", "schema": { "default": 50, "description": "Maximum accepted runs per page, newest first.", "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "Continuation cursor returned by the previous page.", "schema": { "description": "Continuation cursor returned by the previous page.", "type": "string" } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "submissions": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string" }, "definition": { "type": "string" }, "model": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null for the managed default model; omit model in requests to select it." }, "isDefault": { "type": "boolean" }, "version": { "type": "string" } }, "required": [ "key", "isDefault", "version" ], "additionalProperties": false }, "idempotencyKey": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "status": { "type": "string", "const": "accepted" }, "valueCount": { "type": "number" } }, "required": [ "runId", "definition", "model", "idempotencyKey", "generatedAt", "receivedAt", "status", "valueCount" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false } }, "required": [ "submissions", "pagination" ], "additionalProperties": false }, "example": { "submissions": [ { "runId": "m57abc123", "definition": "afrr-capacity-price-de", "model": { "key": null, "isDefault": true, "version": "1.0" }, "idempotencyKey": "forecast-2026-07-27-v1", "generatedAt": "2026-07-26T16:00:00.000Z", "receivedAt": "2026-07-26T16:01:04.000Z", "status": "accepted", "valueCount": 36 } ], "pagination": { "hasMore": false, "nextCursor": null } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/producer/submissions/{id}": { "get": { "operationId": "get-submission", "tags": [ "producer" ], "summary": "Inspect one accepted submission", "description": "Retrieves one of your accepted submissions, its delivery windows and forecast values.\n\nA missing, invalid or inaccessible identifier returns 404 SUBMISSION_NOT_FOUND.\n\nTimestamps use RFC 3339.\n\nAccount rate limit: 120 read requests per minute, with a burst capacity of 30. The token bucket refills continuously and is shared across all API keys of the account and both Customer and Producer read endpoints. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "submissions:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier returned by the catalog or list endpoint.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "submission": { "type": "object", "properties": { "run": { "type": "object", "properties": { "runId": { "type": "string" }, "definition": { "type": "string" }, "model": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null for the managed default model; omit model in requests to select it." }, "isDefault": { "type": "boolean" }, "version": { "type": "string" } }, "required": [ "key", "isDefault", "version" ], "additionalProperties": false }, "idempotencyKey": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "status": { "type": "string", "const": "accepted" }, "valueCount": { "type": "number" } }, "required": [ "runId", "definition", "model", "idempotencyKey", "generatedAt", "receivedAt", "status", "valueCount" ], "additionalProperties": false }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "timezone": { "type": "string" }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "deliveryWindows": { "type": "array", "items": { "type": "object", "properties": { "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "expectedTimestamps": { "type": "number", "description": "Interval starts in the complete local delivery day." }, "timestampCount": { "type": "number", "description": "Distinct submitted interval starts in this delivery day." }, "valueCount": { "type": "number", "description": "Numeric values across all submitted timestamps, series and outputs." }, "coverageRatio": { "type": "number", "description": "Submitted timestamps divided by expected timestamps." }, "deadlineAt": { "description": "Exclusive receipt deadline for a gate-closure delivery day.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "deliveryDay", "expectedTimestamps", "timestampCount", "valueCount", "coverageRatio" ], "additionalProperties": false } }, "values": { "type": "array", "items": { "type": "object", "properties": { "validTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "seriesKey": { "type": "string" }, "outputKey": { "type": "string" }, "value": { "type": "number" }, "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." } }, "required": [ "validTime", "seriesKey", "outputKey", "value", "deliveryDay" ], "additionalProperties": false } } }, "required": [ "run", "resolution", "timezone", "unit", "outputs", "series", "deliveryWindows", "values" ], "additionalProperties": false } }, "required": [ "submission" ], "additionalProperties": false }, "example": { "submission": { "run": { "runId": "m57abc123", "definition": "afrr-capacity-price-de", "model": { "key": null, "isDefault": true, "version": "1.0" }, "idempotencyKey": "forecast-2026-07-27-v1", "generatedAt": "2026-07-26T16:00:00.000Z", "receivedAt": "2026-07-26T16:01:04.000Z", "status": "accepted", "valueCount": 36 }, "resolution": "PT4H", "timezone": "Europe/Berlin", "unit": "EUR_MWH", "outputs": [ { "key": "p10", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.1 }, { "key": "p50", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.5 }, { "key": "p90", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.9 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "deliveryWindows": [ { "deliveryDay": "2026-07-27", "expectedTimestamps": 6, "timestampCount": 6, "valueCount": 36, "coverageRatio": 1, "deadlineAt": "2026-07-27T08:45:00.000Z" } ], "values": [ { "deliveryDay": "2026-07-27", "validTime": "2026-07-26T22:00:00.000Z", "seriesKey": "positive", "outputKey": "p50", "value": 68.4 } ] } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/producer/forecasts/{definition}/data": { "get": { "operationId": "producer-forecast-data", "tags": [ "producer" ], "summary": "Read your point-in-time forecast range", "description": "Retrieves the forecast values your provider account had successfully submitted by a fixed time, over an inclusive range of local delivery dates.\n\nSelection uses receivedAt, not generatedAt. All outputs and series for one interval come from the same accepted submission.\n\nResults may combine several submissions. Customer publication does not affect this endpoint.\n\navailable means at least some values exist; check coverageRatio for completeness.\n\nFollow nextCursor with the same definition, date range and asOf. Pages contain complete local days.\n\nAccount rate limit: 120 read requests per minute, with a burst capacity of 30. The token bucket refills continuously and is shared across all API keys of the account and both Customer and Producer read endpoints. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "submissions:read", "parameters": [ { "name": "definition", "in": "path", "required": true, "description": "Resource identifier returned by the catalog or list endpoint.", "schema": { "type": "string" } }, { "name": "deliveryFrom", "in": "query", "required": true, "description": "First local delivery day, inclusive.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "First local delivery day, inclusive." } }, { "name": "deliveryTo", "in": "query", "required": true, "description": "Last local delivery day, inclusive; at most 366 days per range.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Last local delivery day, inclusive; at most 366 days per range." } }, { "name": "asOf", "in": "query", "required": true, "description": "Availability cutoff; must not be in the future.", "schema": { "type": "string", "allOf": [ { "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "pattern": "T\\d{2}:\\d{2}:\\d{2}" } ], "description": "Availability cutoff; must not be in the future." } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum delivery days per page. Defaults to 7.", "schema": { "default": 7, "description": "Maximum delivery days per page.", "type": "integer", "minimum": 1, "maximum": 8 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque continuation cursor bound to the original request.", "schema": { "description": "Opaque continuation cursor bound to the original request.", "type": "string" } }, { "name": "model", "in": "query", "required": false, "description": "Internal model key; omit for the managed default model.", "schema": { "description": "Internal model key; omit for the managed default model.", "type": "string", "pattern": "\\S" } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requested": { "type": "object", "properties": { "deliveryFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "deliveryTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "limit": { "type": "number" } }, "required": [ "deliveryFrom", "deliveryTo", "asOf", "limit" ], "additionalProperties": false }, "page": { "type": "object", "properties": { "deliveryFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "deliveryTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "deliveryDayCount": { "type": "number" } }, "required": [ "deliveryFrom", "deliveryTo", "deliveryDayCount" ], "additionalProperties": false }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "timezone": { "type": "string" }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "values": { "type": "array", "items": { "type": "object", "properties": { "validTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "seriesKey": { "type": "string" }, "outputKey": { "type": "string" }, "value": { "type": "number" }, "runId": { "type": "string" } }, "required": [ "validTime", "seriesKey", "outputKey", "value", "runId" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false }, "definition": { "type": "string" }, "model": { "type": "object", "properties": { "key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null for the managed default model; omit model in requests to select it." }, "isDefault": { "type": "boolean" } }, "required": [ "key", "isDefault" ], "additionalProperties": false }, "deliveryDays": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "available": { "type": "boolean", "const": true }, "coverageRatio": { "type": "number" }, "runIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "deliveryDay", "available", "coverageRatio", "runIds" ], "additionalProperties": false }, { "type": "object", "properties": { "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "available": { "type": "boolean", "const": false }, "coverageRatio": { "type": "number" }, "reason": { "type": "string", "const": "NO_ACCEPTED_FORECAST_AT_AS_OF" }, "runIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "deliveryDay", "available", "coverageRatio", "reason", "runIds" ], "additionalProperties": false } ] } }, "runs": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string" }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "modelVersion": { "type": "string" } }, "required": [ "runId", "receivedAt", "modelVersion" ], "additionalProperties": false } } }, "required": [ "requested", "page", "resolution", "timezone", "unit", "outputs", "series", "values", "pagination", "definition", "model", "deliveryDays", "runs" ], "additionalProperties": false }, "example": { "definition": "day-ahead-price-de-lu", "model": { "key": "fundamental-v3", "isDefault": false }, "requested": { "deliveryFrom": "2026-08-01", "deliveryTo": "2026-08-02", "asOf": "2026-07-31T10:00:00.000Z", "limit": 7 }, "page": { "deliveryFrom": "2026-08-01", "deliveryTo": "2026-08-02", "deliveryDayCount": 2 }, "resolution": "PT15M", "timezone": "Europe/Berlin", "unit": "EUR_MWH", "outputs": [ { "key": "p50", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.5 } ], "series": [ { "key": "value", "label": "Value" } ], "deliveryDays": [ { "deliveryDay": "2026-08-01", "available": true, "coverageRatio": 1, "runIds": [ "m57newer", "m57older" ] }, { "deliveryDay": "2026-08-02", "available": false, "coverageRatio": 0, "reason": "NO_ACCEPTED_FORECAST_AT_AS_OF", "runIds": [] } ], "runs": [ { "runId": "m57newer", "receivedAt": "2026-07-31T09:00:00.000Z", "modelVersion": "3.0" }, { "runId": "m57older", "receivedAt": "2026-07-31T08:00:00.000Z", "modelVersion": "3.0" } ], "values": [ { "validTime": "2026-07-31T22:00:00.000Z", "seriesKey": "value", "outputKey": "p50", "value": 81.4, "runId": "m57older" }, { "validTime": "2026-07-31T22:15:00.000Z", "seriesKey": "value", "outputKey": "p50", "value": 82.1, "runId": "m57newer" } ], "pagination": { "hasMore": false, "nextCursor": null } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/customer/catalog": { "get": { "operationId": "catalog", "tags": [ "customer" ], "summary": "List published forecast offerings", "description": "Lists the products available to your customer account, with their variants, units, series, outputs and delivery horizons.\n\nRead delivery and output metadata from the selected variant.\n\nfirstDeliveryDayOffset and maxHorizonDays are the first and last allowed delivery-day offsets from today, in the product time zone.\n\nRefresh the catalog to detect configuration changes.\n\nAccount rate limit: 120 read requests per minute, with a burst capacity of 30. The token bucket refills continuously and is shared across all API keys of the account and both Customer and Producer read endpoints. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "catalog:read", "parameters": [], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "variants": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "isDefault": { "type": "boolean" }, "offeringKey": { "type": "string" }, "publicationStatus": { "type": "string", "enum": [ "unpublished", "published" ], "description": "Customer API availability. Public previews remain available for unpublished products." }, "market": { "type": "string" }, "zone": { "type": "string" }, "target": { "type": "string" }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "timezone": { "type": "string" }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "firstDeliveryDayOffset": { "type": "number" }, "maxHorizonDays": { "type": "number" }, "updatePolicy": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "rolling" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "gate_closure" }, "gateDaysBeforeDelivery": { "type": "number" }, "gateLocalTime": { "type": "string" } }, "required": [ "mode", "gateDaysBeforeDelivery", "gateLocalTime" ], "additionalProperties": false } ] }, "historySince": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, { "type": "null" } ], "description": "Earliest published delivery date, or null when no publication exists. Does not guarantee complete coverage." }, "latestReleasedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, { "type": "null" } ], "description": "Most recent publication time, or null when no publication exists." }, "actualSource": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "key", "label", "isDefault", "offeringKey", "publicationStatus", "market", "zone", "target", "resolution", "timezone", "unit", "outputs", "series", "firstDeliveryDayOffset", "maxHorizonDays", "updatePolicy", "historySince", "latestReleasedAt", "actualSource" ], "additionalProperties": false } } }, "required": [ "slug", "title", "description", "category", "variants" ], "additionalProperties": false } } }, "required": [ "products" ], "additionalProperties": false }, "example": { "products": [ { "slug": "afrr-de", "title": "Automatic Frequency Restoration Reserve (aFRR) ยท DE", "description": "Probabilistic forecasts for German aFRR capacity prices, energy prices, and activated reserve power.", "category": "Balancing", "variants": [ { "key": "capacity-price", "label": "Capacity Price", "isDefault": true, "offeringKey": "afrr-capacity-price-de", "publicationStatus": "published", "market": "afrr", "zone": "DE", "target": "capacity-price", "timezone": "Europe/Berlin", "resolution": "PT4H", "unit": "EUR_MWH", "outputs": [ { "key": "p10", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.1 }, { "key": "p50", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.5 }, { "key": "p90", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.9 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "firstDeliveryDayOffset": 1, "maxHorizonDays": 7, "historySince": "2026-07-27", "latestReleasedAt": "2026-07-26T17:00:00.000Z", "updatePolicy": { "mode": "gate_closure", "gateDaysBeforeDelivery": 1, "gateLocalTime": "09:00" }, "actualSource": null }, { "key": "energy-price", "label": "Energy Price", "isDefault": false, "offeringKey": "afrr-energy-price-de", "publicationStatus": "published", "market": "afrr", "zone": "DE", "target": "energy-price", "timezone": "Europe/Berlin", "resolution": "PT15M", "unit": "EUR_MWH", "outputs": [ { "key": "p10", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.1 }, { "key": "p50", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.5 }, { "key": "p90", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.9 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "firstDeliveryDayOffset": 1, "maxHorizonDays": 7, "historySince": "2026-07-27", "latestReleasedAt": "2026-07-26T17:00:00.000Z", "updatePolicy": { "mode": "gate_closure", "gateDaysBeforeDelivery": 1, "gateLocalTime": "09:00" }, "actualSource": null }, { "key": "activations", "label": "Activations", "isDefault": false, "offeringKey": "afrr-activations-de", "publicationStatus": "published", "market": "afrr", "zone": "DE", "target": "activations", "timezone": "Europe/Berlin", "resolution": "PT15M", "unit": "MW", "outputs": [ { "key": "p10", "valueType": "number", "unit": "MW", "quantileLevel": 0.1 }, { "key": "p50", "valueType": "number", "unit": "MW", "quantileLevel": 0.5 }, { "key": "p90", "valueType": "number", "unit": "MW", "quantileLevel": 0.9 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "firstDeliveryDayOffset": 1, "maxHorizonDays": 7, "historySince": "2026-07-27", "latestReleasedAt": "2026-07-26T17:00:00.000Z", "updatePolicy": { "mode": "rolling" }, "actualSource": null } ] } ] } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/customer/forecasts/{offering}/current": { "get": { "operationId": "current-forecast", "tags": [ "customer" ], "summary": "Read the current forecast", "description": "Retrieves the latest published forecast for every requested delivery day.\n\nIf any requested day is unavailable, the entire request returns 404 FORECAST_NOT_PUBLISHED.\n\nOmit start to use the productโ€™s first configured delivery day. Every requested day must fall within the product horizon; otherwise the request returns 422 DELIVERY_DAYS_OUTSIDE_OFFERING_HORIZON.\n\nTimestamps use RFC 3339. Use the unit on the corresponding output.\n\nUse the data endpoint for historical selection and the version endpoint to retrieve a saved version.\n\nAccount rate limit: 120 read requests per minute, with a burst capacity of 30. The token bucket refills continuously and is shared across all API keys of the account and both Customer and Producer read endpoints. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "forecasts:read", "parameters": [ { "name": "offering", "in": "path", "required": true, "description": "Product slug for its default variant, or variants[].offeringKey for a specific variant.", "schema": { "type": "string" } }, { "name": "horizon", "in": "query", "required": false, "description": "Consecutive delivery days, P1D through P8D, subject to the offering horizon. Defaults to P1D.", "schema": { "default": "P1D", "description": "Consecutive delivery days, P1D through P8D, subject to the offering horizon.", "type": "string", "pattern": "^P[1-8]D$" } }, { "name": "start", "in": "query", "required": false, "description": "First local delivery day; defaults to the offering offset.", "schema": { "description": "First local delivery day; defaults to the offering offset.", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "offering": { "type": "string" }, "requested": { "type": "object", "properties": { "horizon": { "type": "string" }, "startDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." } }, "required": [ "horizon" ], "additionalProperties": false }, "resolved": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "timezone": { "type": "string" } }, "required": [ "from", "to", "timezone" ], "additionalProperties": false }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "deliveryDays": { "type": "array", "items": { "type": "object", "properties": { "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "forecastVersionId": { "type": "string" }, "version": { "type": "number" }, "status": { "type": "string", "enum": [ "preliminary", "final", "rolling" ] }, "coverageRatio": { "type": "number" }, "releasedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." } }, "required": [ "deliveryDay", "forecastVersionId", "version", "status", "coverageRatio", "releasedAt" ], "additionalProperties": false } }, "values": { "type": "array", "items": { "type": "object", "properties": { "validTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "seriesKey": { "type": "string" }, "outputKey": { "type": "string" }, "value": { "type": "number" } }, "required": [ "validTime", "seriesKey", "outputKey", "value" ], "additionalProperties": false } } }, "required": [ "offering", "requested", "resolved", "resolution", "unit", "outputs", "series", "deliveryDays", "values" ], "additionalProperties": false }, "example": { "offering": "afrr-activations-de", "requested": { "horizon": "P1D", "startDay": "2026-07-27" }, "resolved": { "from": "2026-07-26T22:00:00.000Z", "to": "2026-07-27T22:00:00.000Z", "timezone": "Europe/Berlin" }, "resolution": "PT15M", "unit": "MW", "outputs": [ { "key": "p10", "valueType": "number", "unit": "MW", "quantileLevel": 0.1 }, { "key": "p50", "valueType": "number", "unit": "MW", "quantileLevel": 0.5 }, { "key": "p90", "valueType": "number", "unit": "MW", "quantileLevel": 0.9 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "deliveryDays": [ { "deliveryDay": "2026-07-27", "forecastVersionId": "n97abc123", "version": 4, "status": "rolling", "coverageRatio": 1, "releasedAt": "2026-07-26T17:00:00.000Z" } ], "values": [ { "validTime": "2026-07-26T22:00:00.000Z", "seriesKey": "negative", "outputKey": "p50", "value": 420.1 }, { "validTime": "2026-07-26T22:00:00.000Z", "seriesKey": "positive", "outputKey": "p50", "value": 385.6 } ] } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/customer/forecasts/{offering}/data": { "get": { "operationId": "forecast-data", "tags": [ "customer" ], "summary": "Read a delivery range at a fixed cutoff or constant lead", "description": "Retrieves historical forecasts using either one knowledge timestamp or a constant decision lead. The range includes both deliveryFrom and deliveryTo, in the product time zone.\n\nSupply either asOf or both relativeTo and leadMinutes. Mixing modes or omitting a partner parameter returns 422.\n\nasOf selects the latest version published at or before that timestamp for each day. A missing day has available: false and reason: NO_VERSION_AT_AS_OF.\n\nrelativeTo=gateClosure uses the local market gate minus leadMinutes. Provider submission lead is not subtracted. Products without a gate return 422 GATE_CLOSURE_NOT_SUPPORTED.\n\nrelativeTo=validTime uses each intervalโ€™s start minus leadMinutes. Zero lead includes releases exactly at the cutoff.\n\nAn interval uses the latest eligible publication containing it. All its series and outputs come from that version. Incomplete intervals are not filled using older versions.\n\nLater publications never fill historical gaps. A day may contain multiple versions; retain interval version IDs for reproducibility.\n\nRelative gaps use NO_VERSION_AT_AS_OF, NO_VALUE_AT_AS_OF, INCOMPLETE_INTERVAL or CUTOFF_NOT_REACHED. Missing intervals have no values rows. available on a day means at least one complete interval; check coverageRatio.\n\nFollow nextCursor with the original product, date range and selection parameters. Relative pages retain evaluatedAt; restart without a cursor to evaluate again.\n\nFor 422 FORECAST_RANGE_TOO_COMPLEX, reduce limit. Contact support if a single day still fails.\n\nAccount rate limit: 120 read requests per minute, with a burst capacity of 30. The token bucket refills continuously and is shared across all API keys of the account and both Customer and Producer read endpoints. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "forecasts:read", "parameters": [ { "name": "offering", "in": "path", "required": true, "description": "Product slug for its default variant, or variants[].offeringKey for a specific variant.", "schema": { "type": "string" } }, { "name": "deliveryFrom", "in": "query", "required": true, "description": "First local delivery day, inclusive.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "First local delivery day, inclusive." } }, { "name": "deliveryTo", "in": "query", "required": true, "description": "Last local delivery day, inclusive; at most 366 days per range.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Last local delivery day, inclusive; at most 366 days per range." } }, { "name": "asOf", "in": "query", "required": false, "description": "Fixed availability cutoff; must not be in the future. Supply either asOf or both relativeTo and leadMinutes.", "schema": { "description": "Fixed availability cutoff; must not be in the future. Supply either asOf or both relativeTo and leadMinutes.", "type": "string", "allOf": [ { "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "pattern": "T\\d{2}:\\d{2}:\\d{2}" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum delivery days per page. Defaults to 7.", "schema": { "default": 7, "description": "Maximum delivery days per page.", "type": "integer", "minimum": 1, "maximum": 8 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque continuation cursor bound to the original request.", "schema": { "description": "Opaque continuation cursor bound to the original request.", "type": "string" } }, { "name": "relativeTo", "in": "query", "required": false, "description": "Explicit reference for the lead: gateClosure (market gate closure) or validTime (delivery interval start). Required with leadMinutes; cannot be combined with asOf.", "schema": { "description": "Explicit reference for the lead: gateClosure (market gate closure) or validTime (delivery interval start). Required with leadMinutes; cannot be combined with asOf.", "type": "string", "enum": [ "gateClosure", "validTime" ] } }, { "name": "leadMinutes", "in": "query", "required": false, "description": "Non-negative whole minutes before the reference time. Required with relativeTo; zero includes releases exactly at the reference time.", "schema": { "description": "Non-negative whole minutes before the reference time. Required with relativeTo; zero includes releases exactly at the reference time.", "type": "integer", "minimum": 0, "maximum": 150119987579 } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "requested": { "type": "object", "properties": { "deliveryFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "deliveryTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "asOf": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "limit": { "type": "number" } }, "required": [ "deliveryFrom", "deliveryTo", "asOf", "limit" ], "additionalProperties": false }, "page": { "type": "object", "properties": { "deliveryFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "deliveryTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "deliveryDayCount": { "type": "number" } }, "required": [ "deliveryFrom", "deliveryTo", "deliveryDayCount" ], "additionalProperties": false }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "timezone": { "type": "string" }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "values": { "type": "array", "items": { "type": "object", "properties": { "validTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "seriesKey": { "type": "string" }, "outputKey": { "type": "string" }, "value": { "type": "number" } }, "required": [ "validTime", "seriesKey", "outputKey", "value" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false }, "offering": { "type": "string" }, "deliveryDays": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "forecastVersionId": { "type": "string" }, "version": { "type": "number" }, "status": { "type": "string", "enum": [ "preliminary", "final", "rolling" ] }, "coverageRatio": { "type": "number" }, "releasedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "available": { "type": "boolean", "const": true } }, "required": [ "deliveryDay", "forecastVersionId", "version", "status", "coverageRatio", "releasedAt", "available" ], "additionalProperties": false }, { "type": "object", "properties": { "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "available": { "type": "boolean", "const": false }, "reason": { "type": "string", "const": "NO_VERSION_AT_AS_OF" } }, "required": [ "deliveryDay", "available", "reason" ], "additionalProperties": false } ] } } }, "required": [ "requested", "page", "resolution", "timezone", "unit", "outputs", "series", "values", "pagination", "offering", "deliveryDays" ], "additionalProperties": false }, { "type": "object", "properties": { "requested": { "type": "object", "properties": { "deliveryFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "deliveryTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "relativeTo": { "type": "string", "enum": [ "gateClosure", "validTime" ] }, "leadMinutes": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "deliveryFrom", "deliveryTo", "relativeTo", "leadMinutes", "limit" ], "additionalProperties": false }, "page": { "type": "object", "properties": { "deliveryFrom": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "deliveryTo": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "deliveryDayCount": { "type": "number" } }, "required": [ "deliveryFrom", "deliveryTo", "deliveryDayCount" ], "additionalProperties": false }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "timezone": { "type": "string" }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "values": { "type": "array", "items": { "type": "object", "properties": { "validTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "seriesKey": { "type": "string" }, "outputKey": { "type": "string" }, "value": { "type": "number" } }, "required": [ "validTime", "seriesKey", "outputKey", "value" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "nextCursor" ], "additionalProperties": false }, "offering": { "type": "string" }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Server time captured on the first page and retained by continuation cursors." }, "deliveryDays": { "type": "array", "items": { "type": "object", "properties": { "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "available": { "type": "boolean" }, "expectedPoints": { "type": "number" }, "availablePoints": { "type": "number" }, "coverageRatio": { "type": "number" } }, "required": [ "deliveryDay", "available", "expectedPoints", "availablePoints", "coverageRatio" ], "additionalProperties": false } }, "intervals": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "validTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "cutoffAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "available": { "type": "boolean", "const": true }, "forecastVersionId": { "type": "string" }, "releasedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." } }, "required": [ "validTime", "cutoffAt", "available", "forecastVersionId", "releasedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "validTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "cutoffAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "available": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "NO_VERSION_AT_AS_OF", "NO_VALUE_AT_AS_OF", "INCOMPLETE_INTERVAL", "CUTOFF_NOT_REACHED" ] } }, "required": [ "validTime", "cutoffAt", "available", "reason" ], "additionalProperties": false } ] }, "description": "One selection record per expected validTime, including gaps. Join values by validTime for cutoff and version provenance." } }, "required": [ "requested", "page", "resolution", "timezone", "unit", "outputs", "series", "values", "pagination", "offering", "evaluatedAt", "deliveryDays", "intervals" ], "additionalProperties": false } ] }, "example": { "offering": "day-ahead-price-de-lu", "requested": { "deliveryFrom": "2026-08-01", "deliveryTo": "2026-08-03", "asOf": "2026-07-31T10:00:00.000Z", "limit": 2 }, "page": { "deliveryFrom": "2026-08-01", "deliveryTo": "2026-08-02", "deliveryDayCount": 2 }, "resolution": "PT15M", "timezone": "Europe/Berlin", "unit": "EUR_MWH", "outputs": [ { "key": "p10", "valueType": "number", "unit": "EUR_MWH" }, { "key": "p50", "valueType": "number", "unit": "EUR_MWH" }, { "key": "p90", "valueType": "number", "unit": "EUR_MWH" } ], "series": [ { "key": "value", "label": "Value" } ], "deliveryDays": [ { "deliveryDay": "2026-08-01", "available": true, "forecastVersionId": "n97abc123", "version": 3, "status": "final", "coverageRatio": 1, "releasedAt": "2026-07-31T09:45:00.000Z" }, { "deliveryDay": "2026-08-02", "available": false, "reason": "NO_VERSION_AT_AS_OF" } ], "values": [ { "validTime": "2026-07-31T22:00:00.000Z", "seriesKey": "value", "outputKey": "p50", "value": 81.4 } ], "pagination": { "hasMore": true, "nextCursor": "eyJ2ZXJzaW9uIjoxLCJvZmZlcmluZ1NsdWciOiJkYXktYWhlYWQtcHJpY2UtZGUtbHUifQ" } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/customer/forecasts/{offering}/versions": { "get": { "operationId": "list-versions", "tags": [ "customer" ], "summary": "List immutable forecast history", "description": "Lists released forecast versions, newest first, so you can find a snapshot to retrieve again.\n\nThis endpoint returns metadata. Retrieve a version by its forecastVersionId to obtain values.\n\nAn unavailable product returns 404 OFFERING_NOT_FOUND.\n\nAccount rate limit: 120 read requests per minute, with a burst capacity of 30. The token bucket refills continuously and is shared across all API keys of the account and both Customer and Producer read endpoints. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "forecasts:read", "parameters": [ { "name": "offering", "in": "path", "required": true, "description": "Product slug for its default variant, or variants[].offeringKey for a specific variant.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum released versions, newest first. Defaults to 30.", "schema": { "default": 30, "description": "Maximum released versions, newest first.", "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "forecastVersionId": { "type": "string" }, "offering": { "type": "string" }, "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "status": { "type": "string", "enum": [ "preliminary", "final", "rolling" ] }, "version": { "type": "number" }, "releasedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "coverageRatio": { "type": "number" }, "valueCount": { "type": "number" } }, "required": [ "forecastVersionId", "offering", "deliveryDay", "status", "version", "releasedAt", "coverageRatio", "valueCount" ], "additionalProperties": false } } }, "required": [ "versions" ], "additionalProperties": false }, "example": { "versions": [ { "forecastVersionId": "n97abc123", "offering": "afrr-capacity-price-de", "deliveryDay": "2026-07-27", "version": 4, "releasedAt": "2026-07-26T17:00:00.000Z", "coverageRatio": 1, "valueCount": 36, "status": "preliminary" } ] } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/customer/forecast-versions/{id}": { "get": { "operationId": "get-version", "tags": [ "customer" ], "summary": "Read one reproducible forecast version", "description": "Retrieves the saved values of one immutable published forecast version.\n\nA missing or invalid identifier returns 404 FORECAST_VERSION_NOT_FOUND.\n\nRetrieving the same version preserves the forecast even after newer versions are published.\n\nAccount rate limit: 120 read requests per minute, with a burst capacity of 30. The token bucket refills continuously and is shared across all API keys of the account and both Customer and Producer read endpoints. Authenticated, authorized requests consume quota even if subsequent validation fails; retries also count. An exhausted bucket returns 429 RATE_LIMIT_EXCEEDED with Retry-After in whole seconds. Wait before retrying; reuse the same Idempotency-Key and payload for a submission retry.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "forecasts:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource identifier returned by the catalog or list endpoint.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "forecastVersion": { "type": "object", "properties": { "forecastVersionId": { "type": "string" }, "offering": { "type": "string" }, "deliveryDay": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, "status": { "type": "string", "enum": [ "preliminary", "final", "rolling" ] }, "version": { "type": "number" }, "releasedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "coverageRatio": { "type": "number" }, "valueCount": { "type": "number" }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "timezone": { "type": "string" }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "values": { "type": "array", "items": { "type": "object", "properties": { "validTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "seriesKey": { "type": "string" }, "outputKey": { "type": "string" }, "value": { "type": "number" } }, "required": [ "validTime", "seriesKey", "outputKey", "value" ], "additionalProperties": false } } }, "required": [ "forecastVersionId", "offering", "deliveryDay", "status", "version", "releasedAt", "coverageRatio", "valueCount", "resolution", "timezone", "unit", "outputs", "series", "values" ], "additionalProperties": false } }, "required": [ "forecastVersion" ], "additionalProperties": false }, "example": { "forecastVersion": { "forecastVersionId": "n97abc123", "offering": "afrr-capacity-price-de", "deliveryDay": "2026-07-27", "version": 4, "releasedAt": "2026-07-26T17:00:00.000Z", "coverageRatio": 1, "valueCount": 36, "status": "preliminary", "resolution": "PT4H", "timezone": "Europe/Berlin", "unit": "EUR_MWH", "outputs": [ { "key": "p10", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.1 }, { "key": "p50", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.5 }, { "key": "p90", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.9 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "values": [ { "validTime": "2026-07-26T22:00:00.000Z", "seriesKey": "positive", "outputKey": "p50", "value": 68.4 } ] } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "429": { "description": "Account request quota exhausted. Wait for Retry-After before retrying.", "headers": { "Retry-After": { "description": "Seconds until a request can be retried.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/public/products": { "get": { "operationId": "products", "tags": [ "public" ], "summary": "List public products", "description": "Lists publicly visible forecast products and their variants without authentication.\n\nfeatured accepts true or false; other values return 422 INVALID_BOOLEAN_FILTER.\n\nPublic visibility does not imply access to authenticated customer forecasts.", "security": [], "parameters": [ { "name": "featured", "in": "query", "required": false, "description": "Return only featured products when true.", "schema": { "description": "Return only featured products when true.", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "variants": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "isDefault": { "type": "boolean" }, "offeringKey": { "type": "string" }, "publicationStatus": { "type": "string", "enum": [ "unpublished", "published" ], "description": "Customer API availability. Public previews remain available for unpublished products." }, "market": { "type": "string" }, "zone": { "type": "string" }, "target": { "type": "string" }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "timezone": { "type": "string" }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "firstDeliveryDayOffset": { "type": "number" }, "maxHorizonDays": { "type": "number" }, "updatePolicy": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "rolling" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "gate_closure" }, "gateDaysBeforeDelivery": { "type": "number" }, "gateLocalTime": { "type": "string" } }, "required": [ "mode", "gateDaysBeforeDelivery", "gateLocalTime" ], "additionalProperties": false } ] }, "historySince": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, { "type": "null" } ], "description": "Earliest published delivery date, or null when no publication exists. Does not guarantee complete coverage." }, "latestReleasedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, { "type": "null" } ], "description": "Most recent publication time, or null when no publication exists." }, "actualSource": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "key", "label", "isDefault", "offeringKey", "publicationStatus", "market", "zone", "target", "resolution", "timezone", "unit", "outputs", "series", "firstDeliveryDayOffset", "maxHorizonDays", "updatePolicy", "historySince", "latestReleasedAt", "actualSource" ], "additionalProperties": false } }, "featured": { "type": "boolean" } }, "required": [ "slug", "title", "description", "category", "variants", "featured" ], "additionalProperties": false } } }, "required": [ "products" ], "additionalProperties": false }, "example": { "products": [ { "slug": "fcr-de", "title": "Frequency Containment Reserve (FCR) ยท DE", "description": "Probabilistic forecast of German FCR capacity prices in local four-hour products.", "category": "Balancing", "featured": false, "variants": [ { "key": "capacity-price", "label": "Capacity Price", "isDefault": true, "offeringKey": "fcr-capacity-price-de", "publicationStatus": "published", "market": "fcr", "zone": "DE", "timezone": "Europe/Berlin", "resolution": "PT4H", "unit": "EUR_MWH", "outputs": [ { "key": "p50", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.5 } ], "series": [ { "key": "symmetric", "label": "Symmetric", "direction": "symmetric" } ], "firstDeliveryDayOffset": 1, "maxHorizonDays": 7, "historySince": "2026-07-27", "latestReleasedAt": "2026-07-26T17:00:00.000Z", "target": "capacity-price", "updatePolicy": { "mode": "gate_closure", "gateDaysBeforeDelivery": 1, "gateLocalTime": "08:00" }, "actualSource": null } ] } ] } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/public/products/{slug}": { "get": { "operationId": "product", "tags": [ "public" ], "summary": "Read public product details", "description": "Retrieves the public description, variants, series, outputs and units of one product.\n\nAn unavailable or unknown product returns 404 PRODUCT_NOT_FOUND.\n\nUse the Customer API for operational forecasts.", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource identifier returned by the catalog or list endpoint.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "product": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "variants": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "isDefault": { "type": "boolean" }, "offeringKey": { "type": "string" }, "publicationStatus": { "type": "string", "enum": [ "unpublished", "published" ], "description": "Customer API availability. Public previews remain available for unpublished products." }, "market": { "type": "string" }, "zone": { "type": "string" }, "target": { "type": "string" }, "resolution": { "type": "string", "enum": [ "PT15M", "PT1H", "PT4H" ] }, "timezone": { "type": "string" }, "unit": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "valueType": { "type": "string", "enum": [ "number", "probability" ] }, "unit": { "type": "string" }, "quantileLevel": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "valueType", "unit" ], "additionalProperties": false } }, "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "direction": { "type": "string" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "firstDeliveryDayOffset": { "type": "number" }, "maxHorizonDays": { "type": "number" }, "updatePolicy": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "rolling" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "gate_closure" }, "gateDaysBeforeDelivery": { "type": "number" }, "gateLocalTime": { "type": "string" } }, "required": [ "mode", "gateDaysBeforeDelivery", "gateLocalTime" ], "additionalProperties": false } ] }, "historySince": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, { "type": "null" } ], "description": "Earliest published delivery date, or null when no publication exists. Does not guarantee complete coverage." }, "latestReleasedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, { "type": "null" } ], "description": "Most recent publication time, or null when no publication exists." }, "actualSource": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": [ "label", "url" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "key", "label", "isDefault", "offeringKey", "publicationStatus", "market", "zone", "target", "resolution", "timezone", "unit", "outputs", "series", "firstDeliveryDayOffset", "maxHorizonDays", "updatePolicy", "historySince", "latestReleasedAt", "actualSource" ], "additionalProperties": false } }, "featured": { "type": "boolean" } }, "required": [ "slug", "title", "description", "category", "variants", "featured" ], "additionalProperties": false } }, "required": [ "product" ], "additionalProperties": false }, "example": { "product": { "slug": "afrr-de", "title": "Automatic Frequency Restoration Reserve (aFRR) ยท DE", "description": "Probabilistic forecasts for German aFRR capacity prices, energy prices, and activated reserve power.", "category": "Balancing", "featured": false, "variants": [ { "key": "capacity-price", "label": "Capacity Price", "isDefault": true, "offeringKey": "afrr-capacity-price-de", "publicationStatus": "published", "market": "afrr", "zone": "DE", "target": "capacity-price", "timezone": "Europe/Berlin", "resolution": "PT4H", "unit": "EUR_MWH", "outputs": [ { "key": "p50", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.5 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "firstDeliveryDayOffset": 1, "maxHorizonDays": 7, "historySince": "2026-07-27", "latestReleasedAt": "2026-07-26T17:00:00.000Z", "updatePolicy": { "mode": "gate_closure", "gateDaysBeforeDelivery": 1, "gateLocalTime": "09:00" }, "actualSource": null }, { "key": "energy-price", "label": "Energy Price", "isDefault": false, "offeringKey": "afrr-energy-price-de", "publicationStatus": "published", "market": "afrr", "zone": "DE", "target": "energy-price", "timezone": "Europe/Berlin", "resolution": "PT15M", "unit": "EUR_MWH", "outputs": [ { "key": "p50", "valueType": "number", "unit": "EUR_MWH", "quantileLevel": 0.5 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "firstDeliveryDayOffset": 1, "maxHorizonDays": 7, "historySince": "2026-07-27", "latestReleasedAt": "2026-07-26T17:00:00.000Z", "updatePolicy": { "mode": "gate_closure", "gateDaysBeforeDelivery": 1, "gateLocalTime": "09:00" }, "actualSource": null }, { "key": "activations", "label": "Activations", "isDefault": false, "offeringKey": "afrr-activations-de", "publicationStatus": "published", "market": "afrr", "zone": "DE", "target": "activated-power", "timezone": "Europe/Berlin", "resolution": "PT15M", "unit": "MW", "outputs": [ { "key": "p50", "valueType": "number", "unit": "MW", "quantileLevel": 0.5 } ], "series": [ { "key": "positive", "label": "Positive", "direction": "positive" }, { "key": "negative", "label": "Negative", "direction": "negative" } ], "firstDeliveryDayOffset": 1, "maxHorizonDays": 7, "historySince": "2026-07-27", "latestReleasedAt": "2026-07-26T17:00:00.000Z", "updatePolicy": { "mode": "rolling" }, "actualSource": null } ] } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } }, "/api/v2/public/products/{slug}/preview": { "get": { "operationId": "preview", "tags": [ "public" ], "summary": "Read released public preview values", "description": "Retrieves one local day of public preview values and available actuals. Gate-closure previews use the last publication before the gate; rolling previews use the last release strictly before delivery minus the selected lead.\n\nHistory is limited to 90 local days. Select a variant and series using the product metadata.\n\nGate-closure previews cover delivery intervals through today. Rolling previews exclude the most recent hour; the boundary is rounded down to a quarter hour and is exclusive.\n\nQuantiles come from the same publication as the point forecast. Products without p50 may return a probability output.\n\nAn unknown product or variant returns 404 PRODUCT_NOT_FOUND.\n\nUse the Customer API for current forecasts and reproducible version selection.", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Resource identifier returned by the catalog or list endpoint.", "schema": { "type": "string" } }, { "name": "variant", "in": "query", "required": false, "description": "Variant key; omit for the default variant.", "schema": { "description": "Variant key; omit for the default variant.", "type": "string", "pattern": "\\S" } }, { "name": "series", "in": "query", "required": false, "description": "Series key; defaults to the first configured series.", "schema": { "description": "Series key; defaults to the first configured series.", "type": "string", "pattern": "\\S" } }, { "name": "leadMinutes", "in": "query", "required": false, "description": "Rolling availability lead in minutes: 5 min, 1 h or 24 h; defaults to 60. Ignored for gate closure.", "schema": { "description": "Rolling availability lead in minutes: 5 min, 1 h or 24 h; defaults to 60. Ignored for gate closure.", "type": "string", "enum": [ "5", "60", "1440" ] } }, { "name": "beforeDay", "in": "query", "required": false, "description": "Exclusive local day cursor returned as nextBeforeDay. Defaults to tomorrow; history is limited to 90 local days.", "schema": { "description": "Exclusive local day cursor returned as nextBeforeDay. Defaults to tomorrow; history is limited to 90 local days.", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Response examples may abbreviate arrays.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "preview": { "type": "object", "properties": { "slug": { "type": "string" }, "variantKey": { "type": "string" }, "seriesKey": { "type": "string" }, "outputKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leadMinutes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "releasedUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "historyFrom": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "nextBeforeDay": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local calendar date in the product time zone (YYYY-MM-DD)." }, { "type": "null" } ] }, "actualStatus": { "anyOf": [ { "type": "string", "enum": [ "provisional", "final" ] }, { "type": "null" } ] }, "values": { "type": "array", "items": { "type": "object", "properties": { "validTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "RFC 3339 timestamp in UTC." }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "p10": { "type": "number" }, "p90": { "type": "number" }, "actual": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "validTime", "value", "actual" ], "additionalProperties": false } } }, "required": [ "slug", "variantKey", "seriesKey", "outputKey", "leadMinutes", "from", "to", "releasedUntil", "historyFrom", "nextBeforeDay", "actualStatus", "values" ], "additionalProperties": false } }, "required": [ "preview" ], "additionalProperties": false }, "example": { "preview": { "slug": "afrr-de", "variantKey": "activations", "outputKey": "p50", "seriesKey": "positive", "leadMinutes": 60, "from": "2026-07-25T22:00:00.000Z", "to": "2026-07-26T22:00:00.000Z", "releasedUntil": "2026-07-26T11:00:00.000Z", "historyFrom": "2026-04-27T22:00:00.000Z", "nextBeforeDay": "2026-07-26", "actualStatus": "provisional", "values": [ { "validTime": "2026-07-26T10:00:00.000Z", "value": 385.6, "actual": null } ] } } } } }, "400": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "401": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "403": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "404": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "409": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "422": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "500": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } }, "502": { "description": "API error. See error.code and retain requestId.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ], "additionalProperties": false } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }