Octopus API basics | Switch to Octopus

Octopus publishes a useful API for tariff data, product metadata and customer account data. You do not need to be a developer to benefit from it, but it helps to understand what the API can and cannot tell you before relying on a spreadsheet, Home Assistant integration or tariff calculator.

This is a practical guide for household-level checks, not official Octopus developer support.

The short version

Use the API for:

Public tariff checks: product codes, regional tariff codes, unit rates and standing charges
Smart-tariff analysis: Agile half-hour prices, Go-style time bands and tariff history
Personal usage analysis: electricity and gas consumption from your own smart meters
Account discovery: meter identifiers, supply points and tariff agreements on your own account

Do not treat the API as a promise that a tariff is available to you personally. Eligibility, meter compatibility, region, payment method, sign-up rules and product closures still need to be checked on the relevant Octopus tariff page or in your account.

What is public and what needs a key?

The product and tariff-rate endpoints are public. You can look up Octopus products, regional electricity tariff codes, gas tariff codes, standing charges and unit rates without being signed in.

Account and consumption endpoints need your personal API key. That key is available from the developer section of your Octopus account dashboard. Keep it private, because it can expose account structure and meter-consumption data.

Authentication uses HTTP Basic Auth with the API key as the username and an empty password:

curl -u "sk_live_or_similar_key:" https://api.octopus.energy/v1/accounts/A-12345678/

The colon at the end matters. It tells curl that the password is blank.

Base URL

REST API requests use:

https://api.octopus.energy/v1/

Octopus also has a separate GraphQL API, but the REST API is simpler for most tariff-rate and consumption checks.

Useful REST endpoints

List products: GET /products/

This returns Octopus products with codes, display names, directions, flags and availability dates. Useful filters include brand=OCTOPUS_ENERGY, is_business=false, is_prepay=false, is_variable=true and available_at=.... The response is paginated, so follow next rather than assuming the first page is the complete product list.

Product details: GET /products/{product_code}/

This shows the product metadata and the regional tariff structures for electricity and gas. Add tariffs_active_at=... if you need to inspect tariffs at a particular point in time rather than today.

Product detail responses can include more than the usual single-register and dual-register tariff groups. The live API also exposes shapes such as four_rate_ev_electricity_tariffs where Octopus uses a device or EV-specific structure. Treat those fields as a prompt to read the live tariff page and terms, not as a reason to guess the billing model from the JSON name alone.

Electricity unit rates: GET /products/{product_code}/electricity-tariffs/{tariff_code}/standard-unit-rates/

This is the endpoint most people use for Agile, Go-style and single-register electricity rates. Use period_from, period_to and page_size to control the returned period. The maximum page size in the current docs is 1500, which is enough for about a month of half-hourly Agile prices.

Octopus’s current REST reference also lists EV-device peak and off-peak unit-rate endpoints for compatible smart-tariff/device data. Do not assume those are the same thing as the whole-home import tariff. For a household bill check, first identify the actual product code, regional tariff code and tariff terms attached to the account.

Electricity standing charges: GET /products/{product_code}/electricity-tariffs/{tariff_code}/standing-charges/

This returns daily standing charges. Standing charges vary by region and payment method, so do not copy one region’s value into general advice.

Gas rates and standing charges: GET /products/{product_code}/gas-tariffs/{tariff_code}/standard-unit-rates/ and GET /products/{product_code}/gas-tariffs/{tariff_code}/standing-charges/

Gas tariff codes use G-1R rather than E-1R.

Account details: GET /accounts/{account_number}/

This authenticated endpoint helps you find MPANs, MPRNs, meter serial numbers and tariff agreements for your own account.

Electricity consumption: GET /electricity-meter-points/{mpan}/meters/{serial_number}/consumption/

This returns half-hourly electricity consumption when smart-meter data is available. You can filter by period and page through the results.

Gas consumption: GET /gas-meter-points/{mprn}/meters/{serial_number}/consumption/

This is the gas equivalent. Check the units carefully, because some gas readings may need conversion before you can compare them with bill kWh.

Grid supply point by postcode: GET /industry/grid-supply-points/?postcode={postcode}

This public endpoint helps identify the regional group used in electricity tariff codes. It is useful when comparing regional pricing without guessing the letter at the end of a tariff code.

The live Octopus documentation still separates the API into product, tariff, account, consumption and price endpoints. A same-day spot check also confirmed that the public product list, product-detail endpoint, standard unit-rate endpoint and postcode-to-grid-supply-point endpoint are returning usable JSON.

Useful checks from this review:

public product and tariff endpoints can show product metadata, tariff-code links, regional unit rates and standing charges
the product list exposes availability, restriction, tracker, prepay, business, direction and term fields, so availability needs a current product-code check rather than a remembered tariff name
product detail responses may expose specialist tariff groups, including EV-specific tariff shapes, so code should inspect the response keys instead of assuming every tariff is a single-register import tariff
the account endpoint can show MPANs, MPRNs, meter serial numbers, registers and current or historic tariff agreements, but it needs the customer’s own API key
consumption endpoints need the MPAN or MPRN, meter serial number and API key, and they only help when the meter data exists
price feeds are time-windowed and paginated, so date ranges, page_size and next links matter for Agile or other half-hourly data

That makes the API useful for checking evidence, stale rates, product-code drift and regional codes. It does not replace the live Octopus tariff page, the smart-tariff terms or the customer’s own account screen when the question is whether a specific home can join or stay on a tariff.

Tariff codes in plain English

A typical single-register electricity tariff code looks like this:

E-1R-AGILE-FLEX-22-11-25-C

The important parts are:

E means electricity
1R means single register
AGILE-FLEX-22-11-25 is the product code
C is the regional electricity group

Most Octopus smart-import tariffs still expose rates through single-register E-1R style tariff codes, even when the prices vary during the day. Agile returns many half-hour records. Go and Intelligent Go-style products return time-banded records. Cosy returns its own time bands.

Legacy Economy 7-style dual-register electricity tariffs use E-2R and separate day and night rate endpoints. Gas uses G-1R.

Common pitfalls

Availability is not eligibility: a product appearing in the API does not mean you can sign up to it. Closed, restricted, export, legacy or technology-specific products need extra checks.

Product codes and response shapes move over time: a fixed product code can be current one month and retired the next, and newer products may expose tariff groups that old scripts do not expect. If a calculator or spreadsheet uses hard-coded product codes or assumes only one response shape, recheck the product metadata before trusting the result.

Regional pricing matters: unit rates and standing charges can vary by electricity region. Always use the tariff code for the right regional group.

Payment method can affect returned rates: some endpoints include different records for Direct Debit and non-Direct-Debit pricing. Check the payment_method field before using a number.

Timestamps are not local diary entries: API timestamps use UTC-style datetimes. During British Summer Time, local evening and overnight windows can cross date boundaries in a way that looks odd if you filter by midnight-to-midnight without thinking about timezone.

Agile needs enough page size: half-hourly prices add up quickly. If you request several days of Agile data, set page_size high enough and follow the next link when the response is paginated.

Consumption data can be incomplete: smart-meter gaps, meter exchanges, register mapping problems and account moves can all create missing or confusing data. If your bill looks wrong, use the API as evidence, not as the only source of truth.

App or API evidence is not the bill itself: API records, Home Assistant charts and app screenshots can explain what happened, but Octopus bills still depend on the account tariff, meter configuration, half-hourly data and tariff terms.

Gas units need checking: do not assume every gas consumption response is already in the bill unit you expect. If you are doing cost calculations, confirm whether the data needs converting to kWh.

What the API is good for

The API is useful when you want to:

compare Octopus tariff rates by region
check whether a price shown in an article or spreadsheet is stale
build a Home Assistant automation for Agile, Go, Cosy or battery charging
pull your own half-hourly usage into a spreadsheet
compare your actual usage pattern against several tariffs
investigate whether missing readings or meter changes explain a confusing bill

It is less useful as a simple answer to “which tariff should I pick?”. For that, you still need your usage pattern, meter setup, EV or heat-pump details, solar or battery position and appetite for price movement.

Where to go next

If you are using the API to make a switching or tariff decision, these guides are usually more useful than raw endpoint output:

If you decide Octopus fits your home after doing the tariff checks, you can still use the Octopus referral link during signup. The API is there to help with the decision; the referral should come after the tariff choice makes sense.