---
title: "Energy flow"
method: GET
path: "/history/flow"
tags: ["experimental"]
---

# Energy flow

`GET /history/flow`

## Request

- Base URL: `https://demo.evcc.io/api`
- URL: `https://demo.evcc.io/api/history/flow`
- Auth: none declared

Returns the energy attributed from sources (pv, battery, grid) to sinks (home, battery, loadpoint, export) over the period, plus grid cost and CO₂ sums where tariff data exists.

## Query parameters

- `from` string, date-time
- `to` string, date-time

## Response `200`

Energy flow data

- object
  - `flows` Flow[]
    - `from` 'pv' | 'battery' | 'grid'
    - `to` 'home' | 'battery' | 'loadpoint' | 'export'
    - `energy` number: kWh
    - `cost` number: Cost of the energy, for home and loadpoint
    - `pricedEnergy` number: kWh where a price exists
  - `entities` object[]: Flows into each consumer and loadpoint, priced per slot
    - `group` 'consumer' | 'loadpoint'
    - `title` string
    - `virtual` boolean: Home consumption not covered by a consumer
    - `flows` Flow[]
      - `from` 'pv' | 'battery' | 'grid'
      - `to` 'home' | 'battery' | 'loadpoint' | 'export'
      - `energy` number: kWh
      - `cost` number: Cost of the energy, for home and loadpoint
      - `pricedEnergy` number: kWh where a price exists
  - `cost` object: Grid cost sums, omitted without grid price data
    - `import` number
    - `export` number
    - `importEnergy` number: kWh where a price exists
    - `exportEnergy` number: kWh where a price exists
    - `avgGrid` number
  - `co2` object: Grid CO₂ sums in kg, omitted without CO₂ data
    - `consumption` number: Emissions of the grid share that went to home and loadpoints
    - `consumptionEnergy` number: kWh
    - `baseline` number
    - `avgCo2` number: g/kWh

## Other responses

- `400`: Invalid parameters or database offline

## Changes

- **2026-10-20** `7f86be85ee98`: 1 info
  - added the optional property `entities` to the response with the `200` status
- **2026-10-05** `7f2e5fedb37a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/evcc-io/apis/evcc/changes/history/flow/get.md)

---

[API](https://skmtc.dev/evcc-io/apis/evcc.md) - [All operations](https://skmtc.dev/evcc-io/apis/evcc/llms.txt) - [OpenAPI document](https://skmtc.dev/evcc-io/apis/evcc/revisions/f6589b1a9e51?raw)