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.

Reviewed May 2026: this page reflects the current Octopus REST API documentation and the public tariff endpoints used by this site. It 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=....

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.

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.

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.

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.

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.

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 Matt’s Octopus referral code during signup. The API is there to help with the decision; the referral should come after the tariff choice makes sense.