Octopus API basics | Switch to Octopus

Octopus Energy has one of the most open and accessible APIs in the UK energy industry. While most suppliers treat their data as proprietary, Octopus makes tariff rates, product information and even your personal consumption data available through a straightforward REST API. It’s one of the reasons the company has built such a strong following among technically minded customers.

What’s available

The API gives you access to several types of data:

Product listings: Every Octopus product (tariff), current and historical
Tariff rates: Unit rates and standing charges for any product, any region, any date range
Your consumption data: Half-hourly electricity and daily gas usage from your smart meter
Account information: Your tariff, meter details and account structure

The product and tariff rate endpoints are publicly accessible. You don’t need to be a customer to look up Agile prices or compare regional standing charges. The consumption and account endpoints require authentication with your personal API key.

Authentication

Your API key is found in your Octopus account dashboard under Developer Settings, or directly at octopus.energy/dashboard/developer/. Your key looks something like sk_live_xxxxxxxxxxxxxxxxxxxx.

To authenticate, use HTTP Basic Auth with your API key as the username and an empty password. In practice, most tools and libraries handle this for you. If you’re using curl, it looks like:

curl -u "sk_live_your_key_here:" https://api.octopus.energy/v1/...

Note the colon after the key. That signifies an empty password.

The base URL

All API requests go to https://api.octopus.energy/v1/. Everything hangs off this root.

Key endpoints

List all products: GET /products/

Returns every product Octopus offers or has offered. Each product has a code (like AGILE-FLEX-22-11-25 or GO-VAR-22-10-14), a display name and metadata about what type of tariff it is. Use the is_variable and is_green flags to filter. Add ?is_prepay=false&is_business=false to narrow to domestic credit tariffs.

Product details: GET /products/{product_code}/

Returns full details for a specific product, including links to all its regional tariff codes. This is where you find the tariff codes you need for rate lookups.

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

Returns unit rates for a specific tariff and region. For flat-rate tariffs, this is a single value. For Agile, it’s 48 half-hourly rates per day. You can filter by date range using period_from and period_to query parameters.

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

Returns the daily standing charge for a tariff and region.

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

Returns your half-hourly electricity consumption data. Requires authentication. Your MPAN and serial number are on your bill or in your account settings. Use period_from, period_to, page_size, order_by and group_by to control the response.

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

Same as above but for gas. Uses your MPRN (Meter Point Reference Number) instead of an MPAN. Note that units returned depend on your meter type (see the gotchas section below).

Your account: GET /accounts/{account_number}/

Returns your account structure: MPANs, MPRNs, meter serial numbers, current and previous tariff agreements. Requires authentication. This is useful for programmatically discovering the identifiers you need for consumption requests.

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

Returns the GSP group letter for a given postcode. Public, no authentication needed. Handy for working out which regional tariff code to use.

Tariff codes explained

Tariff codes follow the pattern E-1R-{PRODUCT_CODE}-{REGION} for single-register electricity tariffs, where the region is a single letter from A to P representing one of the 14 electricity distribution regions. For example, E-1R-AGILE-FLEX-22-11-25-C is the Agile tariff for the London region.

Most smart tariffs (Agile, Go, Intelligent Go, Tracker, Cosy, Flux) use the E-1R prefix, even when they have multiple rate bands. The rates come back with time-of-use information in the valid_from and valid_to fields.

There is one exception: legacy Economy 7 (dual-register) tariffs use the E-2R prefix. These have separate endpoints for day and night rates (day-unit-rates/ and night-unit-rates/) rather than the single standard-unit-rates/ endpoint.

Gas tariff codes follow a similar pattern but use G-1R instead of E-1R.

Rate limits and etiquette

The API does enforce rate limits, though Octopus doesn’t widely publicise the exact thresholds. If you exceed them, you’ll receive a KT-CT-1199 error code. Limits can be static (a fixed number of requests per minute) or dynamic (progressively stricter if you keep exceeding them). For most personal projects, a few requests per minute is plenty. If you’re building something that needs frequent updates (like a live Agile price display), cache the results locally and refresh every few minutes.

Agile prices for the next day are typically published around 4pm (London time), though they can arrive as late as 8pm. There’s no point checking more often than that for forward-looking prices.

Common gotchas

Multi-rate tariffs still use E-1R: Go, Intelligent Go, Tracker, Cosy and Flux all have multiple rates or variable pricing, yet the API serves them through the standard E-1R endpoint with standard-unit-rates/. The rates come back with time-of-use information in the valid_from and valid_to fields. The exception is Economy 7 (dual register), which uses E-2R with separate day-unit-rates/ and night-unit-rates/ endpoints.

Page sizes vary: Agile returns 48 results per day (one per half hour). Go returns 2 (day rate and night rate). The default page size is 100 results, so set your page_size parameter accordingly to avoid missing data across multi-day queries.

Gas consumption units depend on meter type: SMETS1 meters return gas consumption pre-converted to kWh. SMETS2 meters return consumption in cubic metres (m³), and you’ll need to convert to kWh yourself using the calorific value and volume correction factor.

Timestamps are UTC: All times in the API are in UTC. During British Summer Time, this means the day boundaries are at 11pm rather than midnight. Plan your date filtering accordingly.

What people build

The most common projects using the Octopus API include:

Home Assistant integrations: Automating devices based on tariff rates. Charge the battery when Agile is cheap. Run the immersion heater at the off-peak Go rate.
Custom dashboards: Visualising usage and cost data in tools like Grafana.
Price alert bots: Telegram or Discord bots that notify when Agile prices drop below a threshold.
Spreadsheet automations: Pulling rate data into Google Sheets for cost analysis.
Cost calculators: Comparing what your usage would cost on different tariffs. For a practical look at what you can do with consumption data, see our guide to reading your smart meter data.

There’s no official SDK, but community-maintained libraries exist for Python, JavaScript and other languages. A quick search on GitHub will turn up several options.

The GraphQL API

Alongside the REST API described above, Octopus also offers a GraphQL API at https://api.octopus.energy/v1/graphql/. It provides access to account data, tariff information and features like Free Electricity Sessions that aren’t available through the REST endpoints. Authentication uses a token obtained via the obtainKrakenToken mutation rather than HTTP Basic Auth. The GraphQL API always returns a 200 status code, with any errors reported in the response body. For most tariff rate lookups and consumption queries, the REST API is simpler. The GraphQL API is worth exploring if you need account management features or want to build more sophisticated integrations. Documentation is at developer.octopus.energy/graphql/.