> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engrate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Allocations

> Read the energy the market allocates to your accounting points, per settlement period.

After delivery, the market works out how much energy each accounting point consumed or produced in each settlement period. These allocated volumes are what you are settled on. Engrate collects them from the market, together with every later correction, and serves them through one API in each market.

> [!NOTE]
>
> Allocations is an alpha API: it can change without notice.

## Read an accounting point's allocations

**1. Find the accounting point**

Look up the accounting point by the identifier the market gives it, such as its EAN code or market location ID:

```bash theme={null}
curl --request GET \
  --url "https://api.engrate.io/market-access/v1alpha1/timeseries/series/allocations?market_identifier=50123456789" \
  --header "authorization: $API_KEY"
```

```json Response theme={null}
{
  "items": [
    {
      "accounting_point_id": "0ab187fa-a26b-5f61-a061-332db10ee795",
      "flow_direction": "consumption",
      "market_identifier": "50123456789"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 100
}
```

Each series is one flow direction at one accounting point. Leave out the filter to list every series you have allocations for, 100 to a page by default. `total` counts them all; use `offset` and `limit` to read the next page.

**2. Read its volumes**

Ask for a time range. `isp_from` is included and `isp_until` is excluded:

```bash theme={null}
curl --request GET \
  --url "https://api.engrate.io/market-access/v1alpha1/timeseries/allocations?accounting_point_id=0ab187fa-a26b-5f61-a061-332db10ee795&isp_from=2026-10-01T00:00:00%2B02:00&isp_until=2026-10-02T00:00:00%2B02:00" \
  --header "authorization: $API_KEY"
```

```json Response (shortened) theme={null}
{
  "values": [
    { "isp_time": "2026-09-30T22:00:00Z", "volume_wh": 1834, "quality": "provisional", "known_at": "2026-10-02T00:00:00Z" },
    { "isp_time": "2026-09-30T22:00:00Z", "volume_wh": 2241, "quality": "estimated", "known_at": "2026-10-03T00:00:00Z" },
    { "isp_time": "2026-09-30T22:00:00Z", "volume_wh": 2151, "quality": "measured", "known_at": "2026-10-08T00:00:00Z" }
  ]
}
```

Volumes are in watt-hours. Each record also carries `accounting_point_id`, `flow_direction` and `isp_resolution_minutes`.

**3. Pick one value per settlement period**

The first quarter-hour above has three values for consumption: the market sent a provisional figure, then an estimate, then the measured value a week later. Engrate keeps all of them. To get the current figure, take the most trusted `quality` (from least to most: `provisional`, `estimated`, `calculated`, `measured`), then the latest `known_at`:

```python theme={null}
TRUST = {"provisional": 0, "estimated": 1, "calculated": 2, "measured": 3}

current = {}
for v in values:
    key = (v["flow_direction"], v["isp_time"])
    best = current.get(key)
    if best is None or (TRUST[v["quality"]], v["known_at"]) > (TRUST[best["quality"]], best["known_at"]):
        current[key] = v
```

To see the data as it stood at some moment, for example to train a forecast on what was known at 10:00, first drop every value with a later `known_at`.

## Aggregates

The market also sends summed series, such as the total for your balance group in one metering grid area. List the series you receive with `GET /timeseries/series/aggregate-allocations`, and read their values with `GET /timeseries/aggregate-allocations`. Aggregate values carry a `finality` as well as a `quality`. Aggregates are available in Germany.

The [Allocations API overview](https://docs.engrate.io/api-reference/allocations/overview.md) explains how the series and their values are structured, and lists every filter.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.