---
title: "Given an array of historical forecasts, retrieves the data that contains
forecasts metadata, the optimal forecast and a range of forecasts filtered by the attributes [start...end] if provided."
method: POST
path: "/emissions/forecasts/batch"
tags: ["CarbonAware"]
---

# Given an array of historical forecasts, retrieves the data that contains
forecasts metadata, the optimal forecast and a range of forecasts filtered by the attributes [start...end] if provided.

`POST /emissions/forecasts/batch`

This endpoint takes a batch of requests for historical forecast data, fetches them, and calculates the optimal 
marginal carbon intensity windows for each using the same parameters available to the '/emissions/forecasts/current'
endpoint.
            
This endpoint is useful for back-testing what one might have done in the past, if they had access to the 
current forecast at the time.

## Request body

- EmissionsForecastBatchParametersDTO[]
  - `requestedAt` string, date-time, nullable — For historical forecast requests, this value is the timestamp used to access the most recently generated forecast as of that time.
  - `location` string, nullable — The location of the forecast
  - `dataStartAt` string, date-time, nullable — Start time boundary of forecasted data points.Ignores current forecast data points before this time. Defaults to the earliest time in the forecast data.
  - `dataEndAt` string, date-time, nullable — End time boundary of forecasted data points. Ignores current forecast data points after this time. Defaults to the latest time in the forecast data.
  - `windowSize` integer, nullable — The estimated duration (in minutes) of the workload. Defaults to the duration of a single forecast data point.

## Response `200`

Returns the requested forecast objects

- EmissionsForecastDTO[]
  - `generatedAt` string, date-time — Timestamp when the forecast was generated.
  - `requestedAt` string, date-time — For current requests, this value is the timestamp the request for forecast data was made. For historical forecast requests, this value is the timestamp used to access the most recently generated forecast as of that time.
  - `location` string, nullable — The location of the forecast
  - `dataStartAt` string, date-time — Start time boundary of forecasted data points. Ignores forecast data points before this time. Defaults to the earliest time in the forecast data.
  - `dataEndAt` string, date-time — End time boundary of forecasted data points. Ignores forecast data points after this time. Defaults to the latest time in the forecast data.
  - `windowSize` integer — The estimated duration (in minutes) of the workload. Defaults to the duration of a single forecast data point.
  - `optimalDataPoints` EmissionsDataDTO[], nullable — The optimal forecasted data point within the 'forecastData' array. Null if 'forecastData' array is empty.
    - `location` string, nullable
    - `timestamp` string, date-time
    - `duration` integer
    - `value` number, double
  - `forecastData` EmissionsDataDTO[], nullable — The forecasted data points transformed and filtered to reflect the specified time and window parameters. Points are ordered chronologically; Empty array if all data points were filtered out. E.G. dataStartAt and dataEndAt times outside the forecast period; windowSize greater than total duration of forecast data;
    - `location` string, nullable
    - `timestamp` string, date-time
    - `duration` integer
    - `value` number, double

## Other responses

- `400` — Returned if any of the input parameters are invalid
- `500` — Internal server error
- `501` — Returned if the underlying data source does not support forecasting

---

[API](https://skmtc.net/azure/apis/carbonaware-webapi-version-1-0-0-0-culture-neutral-publickey.md) · [All operations](https://skmtc.net/azure/apis/carbonaware-webapi-version-1-0-0-0-culture-neutral-publickey/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/azure/carbonaware-webapi-version-1-0-0-0-culture-neutral-publickey/revisions/5b8513db900a/schema)