get
https://api.etainabl.com/2.0/consumption
This is a general purpose endpoint for getting consumption for accounts, assets, entities and portfolios. Units are converted to kWh or m3 (water only).
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Retrieve aggregated consumption data for a given date range. Data can be retrieved at the account, asset, or entity level, with configurable time granularity.
Endpoint
GET /2.0/consumptionQuery Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
startDate | string | Yes | - | Start date (ISO 8601 format, e.g. 2024-01-01). Normalised to start of day UTC. |
endDate | string | Yes | - | End date (ISO 8601 format, e.g. 2024-12-31). Normalised to start of day UTC. |
granularity | string | No | monthly | Time granularity: halfhourly, hourly, daily, weekly, quarterly, monthly, yearly |
source | string | No | combined | Data source: hh, invoice, reading, custom, combined, reading-hh |
accountType | string | No | - | Filter by utility type (comma-separated). Values: electricity, gas, water, waste, solar, heating, flow, cooling, temperature |
accountId | string | No | - | Retrieve consumption for a specific account |
assetId | string | No | - | Retrieve consumption for a specific asset |
assetGroupId | string | No | - | Retrieve consumption for a specific asset group |
emissions | string | No | false | Include emissions data: true or false |
dayNight | string | No | false | Include day/night consumption breakdown: true or false |
floorArea | string | No | false | Include floor area data: true or false |
capacityInfo | string | No | false | Include demand and capacity data: true or false |
financialInfo | string | No | - | Include cost data (invoice source only): basic or full |
detailedSource | string | No | false | Include source breakdown: true or false |
meterUserBreakdown | string | No | false | Include tenant/landlord breakdown: true or false |
showCounts | string | No | false | Include account and asset counts: true or false |
assetBreakdown | string | No | false | Include per-asset breakdown (when querying by asset group): true or false |
contractCoverage | string | No | false | Include contract coverage counts: true or false |
showSimulated | string | No | false | Include simulated consumption: true or false |
Example Request
curl -X GET "https://api.etainabl.com/2.0/consumption?startDate=2024-01-01&endDate=2024-12-31&accountId=507f1f77bcf86cd799439011&granularity=monthly&emissions=true" \
-H "x-api-key: YOUR_API_KEY"Response
The response includes top-level aggregated values for the entire period, plus a data array with one entry per time period based on the requested granularity.
{
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-12-31T00:00:00.000Z",
"granularity": "monthly",
"units": "kWh",
"consumption": 45000,
"estimatedConsumption": 500,
"isMissing": false,
"sources": ["hh", "invoice"],
"emissions": {
"total": 12000,
"scope1": 0,
"scope2": 12000,
"scope3": 0
},
"accountId": "507f1f77bcf86cd799439011",
"totalConsumption": 45000,
"totalEstimatedConsumption": 500,
"totalEmissions": {
"total": 12000,
"scope1": 0,
"scope2": 12000,
"scope3": 0
},
"data": [
{
"date": "2024-01-01",
"startDate": "2024-01-01T00:00:00.000Z",
"endDate": "2024-02-01T00:00:00.000Z",
"consumption": 3750,
"estimatedConsumption": 42,
"isMissing": false,
"sources": ["hh", "invoice"],
"emissions": {
"total": 1000,
"scope1": 0,
"scope2": 1000,
"scope3": 0
}
},
{
"date": "2024-02-01",
"startDate": "2024-02-01T00:00:00.000Z",
"endDate": "2024-03-01T00:00:00.000Z",
"consumption": 3500,
"estimatedConsumption": 38,
"isMissing": false,
"sources": ["hh"],
"emissions": {
"total": 930,
"scope1": 0,
"scope2": 930,
"scope3": 0
}
}
]
}Response Fields
Top-level Fields (always present)
| Field | Type | Description |
|---|---|---|
startDate | string | Query period start date (ISO 8601 UTC) |
endDate | string | Query period end date (ISO 8601 UTC) |
granularity | string | Requested time granularity |
units | string | Unit of measurement (e.g. kWh, m³, kg). Set to kgco2e for emissions-only queries. |
consumption | number | Total consumption across the period |
estimatedConsumption | number | Total estimated consumption |
isMissing | boolean | Whether complete data coverage exists for the period |
sources | array | List of data sources used (e.g. ["hh", "invoice"]) |
data | array | Array of granular results, one entry per time period |
Top-level Fields (conditional)
| Field | Type | Condition | Description |
|---|---|---|---|
accountId | string | When accountId provided | The queried account ID |
assetId | string | When assetId provided | The queried asset ID |
assetGroupId | string | When assetGroupId provided | The queried asset group ID |
entityId | string | When entityId provided | The queried entity ID |
emissions | object | emissions=true | Emissions breakdown with total, scope1, scope2, scope3 (in kgCO2e) |
simulatedConsumption | number | showSimulated=true | Total simulated consumption |
dayConsumption | number | dayNight=true | Daytime consumption (6am-6pm) |
nightConsumption | number | dayNight=true | Nighttime consumption (6pm-6am) |
tenantConsumption | number | meterUserBreakdown=true | Tenant/renter consumption portion |
landlordConsumption | number | meterUserBreakdown=true | Landlord consumption portion |
maxDemand | number | capacityInfo=true | Maximum demand (kW) |
avgDemand | number | capacityInfo=true | Average demand (kW) |
peakLoad | number | capacityInfo=true | Peak load percentage |
peakCapacity | number | capacityInfo=true | Peak capacity (kW) |
avgCapacity | number | capacityInfo=true | Average capacity (kW) |
cost | number | financialInfo=basic or full, source=invoice | Total cost |
rates | object | financialInfo=full, source=invoice | Cost breakdown with byName and byType objects |
combinedBreakdown | object | source=combined or detailedSource=true | Consumption breakdown by source: { hh, invoice, reading, custom } |
accountFloorArea | number | floorArea=true | Total floor area of accounts (m²) |
assetFloorArea | number | floorArea=true | Total floor area of assets (m²) |
totalAssetFloorArea | number | floorArea=true | Grand total across all assets |
accountCount | number | showCounts=true | Number of accounts included |
assetCount | number | showCounts=true | Number of assets included |
contractCoverage | object | contractCoverage=true | { withContract, withoutContract } count of accounts |
assetGroups | array | assetBreakdown=true with assetGroupId | Per-asset breakdown (see below) |
Backwards Compatibility Fields
These are aliases included for backwards compatibility:
| Field | Alias For |
|---|---|
totalConsumption | consumption |
totalEstimatedConsumption | estimatedConsumption |
totalEmissions | emissions |
Granular Data Array (data)
data)Each element in the data array contains the same fields as the top-level response but scoped to a single time period, plus:
| Field | Type | Description |
|---|---|---|
date | string | Formatted date for the period |
startDate | string | Period start (ISO 8601 UTC) |
endDate | string | Period end (ISO 8601 UTC) |
Asset Groups Array (assetGroups)
assetGroups)When assetBreakdown=true and querying by assetGroupId, each element contains:
| Field | Type | Description |
|---|---|---|
assetId | string | Asset ID |
siteName | string | Site name |
address | string | Site address |
consumption | number | Total consumption for the asset |
emissions | number | Emissions (if emissions=true) |
cost | number | Cost (if financialInfo set) |
accountFloorArea | number | Account floor area (if floorArea=true) |
assetFloorArea | number | Asset floor area (if floorArea=true) |
Scope Required
read:accounts