canonical: https://jentic.com/apis/octopus.energy/octopus-energy # Octopus Energy API Octopus Energy API exposes a single GraphQL endpoint covering UK energy accounts, tariffs, smart-meter consumption readings, agreements, and live wholesale rates. It powers integrations for retail customers, third-party apps, and home-energy automation that need to pull half-hourly meter data, switch tariffs, or query Agile and Go pricing windows. The API is GraphQL-only, so a single POST handles all reads and mutations through typed queries. ## For AI agents Pull smart-meter consumption, query Agile and Go tariff prices, and manage Octopus Energy accounts through a single GraphQL endpoint. ## Scope Does not handle gas or electricity supply switching outside Octopus, payment processing, or non-UK markets - use for Octopus Energy account, meter, and tariff data only. ## Capabilities - Query half-hourly electricity and gas consumption from a smart meter - Retrieve Agile and Go tariff unit rates for a given postcode and time window - Look up account details, properties, and active agreements - Fetch standing charges, standing tariffs, and product comparisons - Pull dispatch schedules for Octopus Go EV and Intelligent tariffs - Submit meter readings or update account preferences via GraphQL mutations ## Use cases ### Smart-home Agile tariff automation Time appliance use to the cheapest half-hourly Agile Octopus rates by querying the live unit-rate stream and scheduling EV charging, hot water, or batteries accordingly. The API returns rates 24 hours ahead, letting home-energy systems plan an optimal schedule and replan as new prices land each afternoon. Example prompt: Query the Agile unit rates for the next 24 hours at a given postcode and return the three half-hourly windows with the lowest pence-per-kWh price ### Energy-usage dashboards Build personal or estate-wide dashboards showing electricity and gas consumption against tariff cost. The API returns half-hourly readings keyed to MPAN/MPRN, which can be aggregated into daily, weekly, or monthly views and joined with the active tariff rate to compute spend. Example prompt: Fetch the last 7 days of half-hourly electricity consumption for a specified MPAN and aggregate it into daily kWh totals ### EV charging dispatch verification For Intelligent Octopus and Go customers, query the dispatch schedule to verify that the charger is being slotted into the smart-charge window and that the cheap-rate hours will apply. This is essential for fleet operators and home-energy apps that need to confirm a charge happened at the off-peak rate. Example prompt: Retrieve tonight's planned dispatches for an Intelligent Octopus account and report the start and end times along with expected energy in kWh ### AI agent energy assistant via Jentic AI agents acting as personal energy assistants use Jentic to call the GraphQL endpoint without writing custom GraphQL clients. The agent searches Jentic for an intent like 'get my electricity usage', loads the operation schema, and executes - Jentic handles the basic-auth header and the GraphQL query construction. Example prompt: Search Jentic for an Octopus Energy consumption query, load the schema, and execute it for the current month's usage ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v1/graphql | Single GraphQL endpoint for all account, consumption, tariff, and dispatch queries and mutations | ## Key resources - **GraphQL** — Single /v1/graphql endpoint serving all queries and mutations across accounts, meters, tariffs, and dispatches ## Why Jentic - **Setup:** Wiring the Octopus Energy API by hand means setting up its basic-auth header and hand-writing GraphQL documents and variables against the single /v1/graphql endpoint. Through Jentic you install once, import Octopus Energy from the API Directory, store the API key once, and your agent calls it. - **Permission scoping:** The Octopus Energy API is a single GraphQL endpoint with no resource id in the URL path, so scoping is by operation: you limit the agent to the operations it needs, such as reading account, meter, and tariff data, and it can call nothing else. - **Credential handling:** Your Octopus Energy API key is stored once, encrypted, by your own Jentic One instance and injected into the basic-auth Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'get my electricity consumption', and Jentic returns the matching operation with the GraphQL document and variables prepared so the agent calls it without browsing the reference docs. ## Related APIs - **OpenWeatherMap API** — Pair weather forecasts with energy data for solar generation or heating-load predictions - **WeatherAPI.com** — Forecast and historical weather data for normalising energy use against temperature - **Oil Price API** — Wholesale energy and fuel prices as a market-facing alternative when retail account access is not needed ## FAQ ### What authentication does the Octopus Energy API use? The API uses HTTP Basic authentication with your account's API key as the username and an empty password. Through Jentic, the API key is stored encrypted in the vault and the basic auth header is constructed at request time, so the raw key never enters the agent's context. ### Can I query half-hourly consumption with the Octopus Energy API? Yes. The GraphQL schema exposes consumption queries that return half-hourly readings for a given MPAN (electricity) or MPRN (gas) over a date range. Smart meters must be enrolled and reporting through DCC for the data to be available. ### What are the rate limits for the Octopus Energy API? Octopus Energy applies a soft rate limit on the GraphQL endpoint. Excessive bursts return 429 responses. Design agents to batch GraphQL queries (consumption, tariffs, and dispatches in one document) rather than firing many small requests. ### How do I get Agile tariff prices through Jentic? Search Jentic for 'octopus agile unit rates', load the GraphQL operation schema, and execute it with a postcode and a time window. Jentic returns the half-hourly unit rates as JSON; no GraphQL client wiring is required. ### Is the Octopus Energy API free to use? Yes for Octopus Energy account holders. The API is provided to retail customers and approved third parties without an additional fee - you authenticate with the same API key shown on your octopus.energy dashboard. Bulk or commercial use cases may require contacting Octopus Energy directly. ### Does the Octopus Energy API support meter-reading submission? Yes. The GraphQL schema exposes mutations to submit manual meter readings against a registered MPAN or MPRN. Submitted readings appear on the account dashboard and feed into the next bill cycle. ### Can I limit what my agent is allowed to do with the Octopus Energy API? Yes. Because the Octopus Energy API is a single GraphQL endpoint with no resource id in the URL path, Jentic One scopes access by operation, and since you self-host it, your own rules decide which operations the agent may call. You can allow read-only operations such as querying account details, half-hourly meter consumption, and Agile or Go tariff rates while blocking mutations like submitting meter readings or updating account preferences. Jentic One also holds your API key and injects it into the basic-auth header at request time, so the agent can only reach the operations you have permitted with the credentials you control.