Energy consumption and cost
octopus_get_consumptionRetrieve smart meter electricity or gas readings totalled by half-hour, hour, day, week, or month in UK time, with estimated costs from the active tariff including unit rates and standing charges.
Instructions
Get smart meter readings for electricity (import or export) or gas, totalled by half-hour, hour, day, week or month in UK time, with an estimated cost from the tariff that was active at the time: the actual unit rate for every half-hour (so Agile, Go and other time-of-use tariffs are priced correctly) plus standing charges, including VAT. Readings come from the smart meter, usually a day behind; there is no data for meters that aren't smart or don't send half-hourly reads. Electricity is in kWh. SMETS2 gas meters report m³, which is converted to kWh for costing with the standard formula (m³ × 1.02264 × calorific value ÷ 3.6). For export meters the estimate is what Octopus pays you. Day/night (Economy 7) tariffs are priced assuming night hours of 00:30 to 07:30 GMT, which may not match your meter. Estimates exclude discounts and credits; your bill is the source of truth.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "octopus_get_consumption"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End: a date (inclusive, the whole day), a date and time, or now/today/yesterday (default the end of yesterday) | |
| from | No | Start: a date (YYYY-MM-DD, UK time), a date and time, or today/yesterday (default 7 days ago) | |
| fuel | No | electricity (default) or gas | |
| limit | No | Return at most this many rows, the most recent (default 400); use a coarser group_by for long periods | |
| serial | No | A specific meter serial number (default: the meter point's meter that has readings) | |
| group_by | No | How to total the half-hourly readings: half_hour, hour, day (default), week (Monday to Sunday), month or total | |
| direction | No | For electricity: import (default, what you use) or export (what you send to the grid, e.g. from solar panels) | |
| gas_units | No | Override the units a gas meter reports in: kwh or m3 (default: as Octopus says for the meter, otherwise m3, which SMETS2 meters use) | |
| meter_point | No | A specific MPAN (electricity) or MPRN (gas), when the account has several (see octopus_get_account) | |
| include_cost | No | Estimate the cost (or export earnings) from the tariff's actual unit rates and standing charges (default true) | |
| account_number | No | Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see) | |
| calorific_value | No | Gas calorific value in MJ/m³ for converting m³ to kWh (default 39.5; your bill shows the actual value) |