---
title: "Monthly utility cost, energy and carbon by resource"
method: POST
path: "/utility/series"
---

# Monthly utility cost, energy and carbon by resource

`POST /utility/series`

Aggregates emission rows classified with the given usage (default building) by calendar month of start_time and utility resource. Costs are split into energy cost (carbon rows) and other charges (standing charges, levies) per currency. Rows of soft-deleted source records are excluded. At most 120 months.

## Request body

- UtilitySeriesRequest
  - `endMonth` string, required
  - `startMonth` string, required
  - `usage` 'building' | 'vehicle' — Which utility rows to aggregate (building energy and water, or vehicle fuel).

## Response `200`

Utility series

- UtilitySeriesResponse
  - `data` UtilitySeries, required
    - `coverage` UtilityCoverage[], required — Per resource, how many months in the range have data.
      - `monthsWithData` integer, required
      - `resource` 'electricity' | 'natural_gas' | 'lpg' | 'heating_oil' | 'gas_oil' | 'diesel' | 'petrol' | 'water' | 'waste' | 'heat_steam' | 'other', required
    - `endMonth` string, required
    - `grossBills` integer, required — Source documents in the range with this usage whose cost was extracted including VAT; the page warns that these may include VAT.
    - `rows` UtilitySeriesRow[], required — One row per month and resource that has data, ordered by month then resource.
      - `carbonKg` number, double, required — Includes upstream rows (well-to-tank, transmission and distribution) of this resource; energyKwh and quantities exclude them.
      - `costs` UtilityCost[], required
        - `currency` string, required — ISO-4217 code; empty string when the bill line's currency is unknown.
        - `energyCost` number, double, required — Spend on carbon rows.
        - `otherCharges` number, double, required — Spend on non-carbon rows (standing charges, levies).
      - `energyKwh` number, double, nullable, required — Sum of kWh-convertible rows; null when no row in this month/resource could be converted (e.g. litres) - read quantities. Excludes upstream rows (well-to-tank, transmission and distribution).
      - `month` string, required
      - `quantities` UtilityQuantity[], required — Activity quantities by unit; spend-based rows are not included.
        - `quantity` number, double, required
        - `unit` string, required
      - `resource` 'electricity' | 'natural_gas' | 'lpg' | 'heating_oil' | 'gas_oil' | 'diesel' | 'petrol' | 'water' | 'waste' | 'heat_steam' | 'other', required
      - `rowCount` integer, required — Includes upstream rows (well-to-tank, transmission and distribution) of this resource; energyKwh and quantities exclude them.
    - `startMonth` string, required
    - `unassigned` UtilityUnassigned, required — Diesel and gas oil rows in the range with no building or vehicle cue.
      - `rows` integer, required
      - `spend` UtilityAmount[], required
        - `amount` number, double, required
        - `currency` string, required
    - `usage` 'building' | 'vehicle', required — Which utility rows to aggregate (building energy and water, or vehicle fuel).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

## Changes

- **2026-10-01** `b4751fd15397` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greentally/apis/esgai-api/changes/utility/series/post.md)

---

[API](https://skmtc.dev/greentally/apis/esgai-api.md) · [All operations](https://skmtc.dev/greentally/apis/esgai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greentally/apis/esgai-api/revisions/b4751fd15397?raw)