Topology: Balance

Base URL: $BUSINESS_API

Compute a DMA water balance over [from, to)

Logs

GET /topology/balance/dma/{id}

Read-only. Inflow comes from the DMA's inflow device, outflow is authorised consumption (billed plus unbilled metered) plus metered export. Check status before trusting the loss figure.

Parameters

idstring · path · required

ID of the district metered area (DMA) to balance; it must belong to the caller's tenant, and the window comes from the required from and to parameters (RFC 3339 instants or YYYY-MM-DD dates read as midnight UTC, at most 366 days apart).

fromstring · query · required

RFC 3339 instant or date

tostring · query · required

RFC 3339 instant or date; at most 366 days after from

Returns

200 Balance

Show attributes
dma_idstring · optional
dma_codestring · optional
node_idstring · optional
period_startstring (date-time) · optional
period_endstring (date-time) · optional
inflow_volume_litersinteger (int64) · optional
export_volume_litersinteger (int64) · optional
outflow_volume_litersinteger (int64) · optional

Authorised consumption plus export

storage_delta_litersinteger (int64) · optional
authorised_consumption_litersinteger (int64) · optional
billed_consumption_litersinteger (int64) · optional
unbilled_metered_consumption_litersinteger (int64) · optional
estimated_consumption_litersinteger (int64) · optional
unaccounted_loss_litersinteger (int64) · optional
non_revenue_water_litersinteger (int64) · optional
loss_basis_pointsinteger · optional · nullable
tolerance_basis_pointsinteger (int64) · optional
physically_validboolean · optional
mass_conservedboolean · optional
statusstring · optional

one of computed, partial_data, insufficient_data

inflowobject · optional
Show child attributes
sourcestring · optional

one of measurements, meter_consumption, none

device_idstring · optional
sample_countinteger · optional
first_observed_atstring (date-time) · optional
last_observed_atstring (date-time) · optional
completeboolean · optional
exportobject · optional
Show child attributes
sourcestring · optional

one of measurements, meter_consumption, none

device_idstring · optional
sample_countinteger · optional
first_observed_atstring (date-time) · optional
last_observed_atstring (date-time) · optional
completeboolean · optional
storageobject · optional
Show child attributes
sourcestring · optional

one of measurements, meter_consumption, none

device_idstring · optional
sample_countinteger · optional
first_observed_atstring (date-time) · optional
last_observed_atstring (date-time) · optional
completeboolean · optional
consumptionobject · optional
Show child attributes
attributionstring · optional

one of dma_taps, service_area, none

meter_countinteger · optional
billed_recordsinteger · optional
unbilled_recordsinteger · optional
proratedboolean · optional
skipped_recordsinteger · optional
warningsarray of string · optional

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/balance/dma/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "dma_code": "DMA-2026-000142",
  "node_id": "nod_26enLAulDEgfZ0IlNWY59ugfRs0",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "inflow_volume_liters": 1342,
  "export_volume_liters": 1342,
  "outflow_volume_liters": 1342,
  "storage_delta_liters": 1,
  "authorised_consumption_liters": 1342,
  "billed_consumption_liters": 1342,
  "unbilled_metered_consumption_liters": 1342,
  "estimated_consumption_liters": 1342,
  "unaccounted_loss_liters": 1,
  "non_revenue_water_liters": 1,
  "loss_basis_points": 1,
  "tolerance_basis_points": 1,
  "physically_valid": true,
  "mass_conserved": true,
  "status": "computed",
  "inflow": {
    "source": "measurements",
    "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
    "sample_count": 1,
    "first_observed_at": "2026-11-19T09:30:00Z",
    "last_observed_at": "2026-11-19T09:30:00Z",
    "complete": true
  },
  "export": {
    "source": "measurements",
    "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
    "sample_count": 1,
    "first_observed_at": "2026-11-19T09:30:00Z",
    "last_observed_at": "2026-11-19T09:30:00Z",
    "complete": true
  },
  "storage": {
    "source": "measurements",
    "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
    "sample_count": 1,
    "first_observed_at": "2026-11-19T09:30:00Z",
    "last_observed_at": "2026-11-19T09:30:00Z",
    "complete": true
  },
  "consumption": {
    "attribution": "dma_taps",
    "meter_count": 1,
    "billed_records": 1,
    "unbilled_records": 1,
    "prorated": true,
    "skipped_records": 1
  },
  "warnings": [
    "warning"
  ]
}

Record a closed period's balance in the immutable ledger

Logs

POST /topology/balance/dma/{id}/ledger

A changed result is appended as a new revision; an unchanged retry returns the existing row.

Parameters

idstring · path · required

ID of the district metered area (DMA) whose balance is computed and written to the ledger; the DMA must have a dma_inlet node to book the entry against, otherwise the request fails with 409.

Body application/json

fromstring (date-time) · required
tostring (date-time) · required

Returns

201 Ledger row

Show attributes
idstring · optional
tenant_idstring · optional
node_idstring · optional
dma_idstring · optional
period_startstring (date-time) · optional
period_endstring (date-time) · optional
revisioninteger · optional
inflow_volume_litersinteger (int64) · optional
outflow_volume_litersinteger (int64) · optional
storage_delta_litersinteger (int64) · optional
unaccounted_loss_litersinteger (int64) · optional
mass_conservedboolean · optional
tolerance_basis_pointsinteger (int64) · optional
created_bystring · optional
created_atstring (date-time) · optional

Errors 409

Permissions network:write · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/topology/balance/dma/{id}/ledger" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from": "2026-11-19T09:30:00Z",
  "to": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "id": "mas_2wu1XsIbbYSzvquXn8uHx44l3Eo",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "node_id": "nod_26enLAulDEgfZ0IlNWY59ugfRs0",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "revision": 1,
  "inflow_volume_liters": 1342,
  "outflow_volume_liters": 1342,
  "storage_delta_liters": 1,
  "unaccounted_loss_liters": 1,
  "mass_conserved": true,
  "tolerance_basis_points": 1,
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z"
}

List mass balance ledger rows, newest first

Logs

GET /topology/balance/ledger

Returns the immutable mass balance ledger entries recorded for the tenant, newest first, with cursor pagination (limit defaults to 20, maximum 100; pass next_cursor as after). A restated period appears as a new entry with a higher revision, because entries are never changed. Requires network read access.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

node_idstring · query · optional

Returns only entries booked against this topology node ID, normally a DMA's dma_inlet node; an exact match, omitted for all nodes.

dma_idstring · query · optional

Returns only entries recorded for this district metered area ID; an exact match, omitted for all DMAs.

Returns

200 Ledger rows

Show attributes
dataarray of MassBalanceEntry · optional
Show child attributes
idstring · optional
tenant_idstring · optional
node_idstring · optional
dma_idstring · optional
period_startstring (date-time) · optional
period_endstring (date-time) · optional
revisioninteger · optional
inflow_volume_litersinteger (int64) · optional
outflow_volume_litersinteger (int64) · optional
storage_delta_litersinteger (int64) · optional
unaccounted_loss_litersinteger (int64) · optional
mass_conservedboolean · optional
tolerance_basis_pointsinteger (int64) · optional
created_bystring · optional
created_atstring (date-time) · optional
has_moreboolean · optional
next_cursorstring · optional

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/balance/ledger" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "mas_2wu1XsIbbYSzvquXn8uHx44l3Eo",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_id": "nod_26enLAulDEgfZ0IlNWY59ugfRs0",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "period_start": "2026-11-19T09:30:00Z",
      "period_end": "2026-11-19T09:30:00Z",
      "revision": 1,
      "inflow_volume_liters": 1342,
      "outflow_volume_liters": 1342,
      "storage_delta_liters": 1,
      "unaccounted_loss_liters": 1,
      "mass_conserved": true,
      "tolerance_basis_points": 1,
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}