Versions & reproducibility

Use a customer API key. A released version is immutable: retrieving the same ID preserves the forecast even after a newer release.

When forecasts update

Forecasts update as new data becomes available. The frequency can vary by product and day; there is no guaranteed hourly update.

Rolling forecasts can update throughout the day. For gate-closure products, forecasts can change before the submission deadline. Once a forecast is marked final, it no longer changes, even if its values are the same as the previous version.

Get notified via webhooks when a new version is available.

List released versions

Set TELESCOPE_OFFERING to a slug or offering key from the catalog, as in First forecast. List its released versions, newest first:

curl "https://telescope.energy/api/v2/customer/forecasts/$TELESCOPE_OFFERING/versions?limit=20" \
  -H "Authorization: Bearer $TELESCOPE_API_KEY"

limit is optional, defaults to 30, and accepts values from 1 through 100.

Illustrative response excerpt:

{
  "versions": [
    {
      "forecastVersionId": "n97abc123",
      "deliveryDay": "2026-07-27",
      "status": "rolling",
      "version": 4,
      "releasedAt": "2026-07-26T17:00:00.000Z",
      "coverageRatio": 1,
      "valueCount": 36,
      "offering": "afrr-activations-de"
    }
  ]
}

The list contains metadata only. Retrieve one immutable version and its complete value series using its forecastVersionId:

curl 'https://telescope.energy/api/v2/customer/forecast-versions/n97abc123' \
  -H "Authorization: Bearer $TELESCOPE_API_KEY"

Illustrative response excerpt:

{
  "forecastVersion": {
    "forecastVersionId": "n97abc123",
    "deliveryDay": "2026-07-27",
    "status": "rolling",
    "version": 4,
    "releasedAt": "2026-07-26T17:00:00.000Z",
    "coverageRatio": 1,
    "valueCount": 36,
    "offering": "afrr-activations-de",
    "resolution": "PT15M",
    "timezone": "Europe/Berlin",
    "unit": "MW",
    "outputs": [
      {
        "key": "p50",
        "valueType": "number",
        "unit": "MW"
      }
    ],
    "series": [
      {
        "key": "positive",
        "label": "Positive"
      }
    ],
    "values": [
      {
        "validTime": "2026-07-26T22:00:00.000Z",
        "seriesKey": "positive",
        "outputKey": "p50",
        "value": 68.4
      }
    ]
  }
}

Store provenance

For operational use, request the current forecast and store each forecastVersionId alongside your result. For audits or recalculation, retrieve the immutable version by ID rather than requesting current again.

For historical comparisons, use a fixed asOf to reproduce one knowledge snapshot, or relativeTo with leadMinutes to compare forecasts at a constant decision lead. Keep the selected version IDs and calculated cutoffs: a relative day can contain intervals from several versions.

When a version is unavailable

Use IDs returned to your own integration and check product access. For failures, retain the requestId and consult troubleshooting.

Next steps

Webhooks include changed version IDs and a link to a fixed snapshot of your full forecast horizon. Use historical data to select versions by decision time, or inspect the version endpoint.