{"openapi":"3.0.3","info":{"title":"Grid and energy data (Agent Data API)","description":"Wholesale electricity prices per market region (AEMO NEM, Elexon GB, ENTSO-E EU zones, EIA US balancing authorities), grid demand and generation by fuel, NESO carbon intensity, derived cheapest-window signals for charging and demand response, and EIA weekly petroleum inventories. One schema across four market structures: UTC timestamps, integer micro units, region codes in one list.","version":"2026.11.09"},"paths":{"/api/v1/regions":{"get":{"tags":["Grid and energy data"],"summary":"Market regions","description":"Every market region we serve with market, timezone, currency, source and price cadence. Refreshes every 24 hours.","operationId":"grid_regions","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"market","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Market","description":"nem, gb, eu or us","examples":["nem"]},"description":"nem, gb, eu or us"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"grid_regions","x-cadence":"Refreshes every 24 hours."}},"/api/v1/power/prices/{market}/{region}":{"get":{"tags":["Grid and energy data"],"summary":"Latest wholesale price","description":"The latest settled wholesale electricity price for a region: NEM 5-minute RRP, GB half-hourly market index price, EU hourly day-ahead price for the current interval. Micro units of the local currency plus a USD conversion at the central bank reference rate. US regions have no price (ISO terms pending): 404. Refreshes every 5 minutes.","operationId":"grid_price","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"market","in":"path","required":true,"schema":{"type":"string","title":"Market"},"example":"nem"},{"name":"region","in":"path","required":true,"schema":{"type":"string","title":"Region"},"example":"NSW1"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"grid_price","x-cadence":"Refreshes every 5 minutes."}},"/api/v1/power/prices/{market}/{region}/day-ahead":{"get":{"tags":["Grid and energy data"],"summary":"Day-ahead or pre-dispatch prices for a day","description":"Forecast prices per interval for one local calendar day: the ENTSO-E day-ahead auction for EU zones (published around 13:00 CET), AEMO pre-dispatch for NEM regions (next 40 hours, 30-minute). GB and US regions answer with basis 'unavailable'. Refreshes every 30 minutes.","operationId":"grid_day_ahead","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"market","in":"path","required":true,"schema":{"type":"string","title":"Market"},"example":"nem"},{"name":"region","in":"path","required":true,"schema":{"type":"string","title":"Region"},"example":"NSW1"},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date","nullable":true,"title":"Date","description":"Local calendar day, default tomorrow","examples":["2026-11-10"]},"description":"Local calendar day, default tomorrow"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"grid_day_ahead","x-cadence":"Refreshes every 30 minutes."}},"/api/v1/power/prices/{market}/{region}/history":{"get":{"tags":["Grid and energy data"],"summary":"Price history (7 days, Pro)","description":"Settled prices per interval for the last 7 days, newest last, optionally averaged to 30m or 60m buckets. Refreshes every 5 minutes.","operationId":"grid_price_history","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"market","in":"path","required":true,"schema":{"type":"string","title":"Market"},"example":"nem"},{"name":"region","in":"path","required":true,"schema":{"type":"string","title":"Region"},"example":"NSW1"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"title":"From","description":"ISO UTC start, default 7 days ago"},"description":"ISO UTC start, default 7 days ago"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"title":"To","description":"ISO UTC end, default now"},"description":"ISO UTC end, default now"},{"name":"interval","in":"query","required":false,"schema":{"type":"string","description":"native, 30m or 60m","example":"30m","default":"native","title":"Interval"},"description":"native, 30m or 60m"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.02","x-price":{"price_micro":20000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"grid_price_history","x-cadence":"Refreshes every 5 minutes.","x-cache-ttl-s":1800}},"/api/v1/power/load/{market}/{region}":{"get":{"tags":["Grid and energy data"],"summary":"Latest grid demand","description":"Latest demand for a region in MW: NEM total demand (5-minute), GB initial demand outturn (30-minute), ENTSO-E actual load (15 or 60-minute), EIA hourly demand for US balancing authorities. Refreshes every 5 minutes.","operationId":"grid_load","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"market","in":"path","required":true,"schema":{"type":"string","title":"Market"},"example":"nem"},{"name":"region","in":"path","required":true,"schema":{"type":"string","title":"Region"},"example":"NSW1"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"grid_load","x-cadence":"Refreshes every 5 minutes."}},"/api/v1/power/generation/{market}/{region}":{"get":{"tags":["Grid and energy data"],"summary":"Latest generation mix","description":"Latest generation by fuel for a region in MW with the total and the renewables share in basis points (GB, EU zones and US balancing authorities; NEM regions have no public fuel split in DispatchIS and answer pending). Refreshes every 5 minutes.","operationId":"grid_generation","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"market","in":"path","required":true,"schema":{"type":"string","title":"Market"},"example":"nem"},{"name":"region","in":"path","required":true,"schema":{"type":"string","title":"Region"},"example":"NSW1"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"grid_generation","x-cadence":"Refreshes every 5 minutes."}},"/api/v1/power/windows/{market}/{region}":{"get":{"tags":["Grid and energy data"],"summary":"Cheapest charging window","description":"The cheapest contiguous window of N hours within the next horizon hours, from day-ahead (EU) or pre-dispatch (NEM) prices, with the GB carbon forecast where the region is GB. Other regions answer basis 'unavailable'. Refreshes every 30 minutes.","operationId":"grid_cheapest_window","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"market","in":"path","required":true,"schema":{"type":"string","title":"Market"},"example":"nem"},{"name":"region","in":"path","required":true,"schema":{"type":"string","title":"Region"},"example":"NSW1"},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":12,"minimum":1,"example":4,"default":4,"title":"Hours"}},{"name":"horizon","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"example":24,"default":24,"title":"Horizon"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.015","x-price":{"price_micro":15000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"grid_cheapest_window","x-cadence":"Refreshes every 30 minutes."}},"/api/v1/carbon/{region}":{"get":{"tags":["Grid and energy data"],"summary":"Grid carbon intensity","description":"gCO2 per kWh for Great Britain (region GB: actual and forecast for the current half hour) or a NESO distribution region id 1 to 17 (forecast and generation mix in basis points). Refreshes every 30 minutes.","operationId":"grid_carbon","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"region","in":"path","required":true,"schema":{"type":"string","example":"GB","title":"Region"},"example":"GB"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"grid_carbon","x-cadence":"Refreshes every 30 minutes."}},"/api/v1/petroleum/weekly":{"get":{"tags":["Grid and energy data"],"summary":"EIA weekly petroleum inventories","description":"The latest EIA weekly US petroleum figure for a series (crude_stocks, gasoline_stocks, distillate_stocks, refinery_inputs, crude_imports) with the previous week and the change. Published Wednesdays 10:30 ET. Refreshes every 7 days.","operationId":"petroleum_weekly","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"series","in":"query","required":false,"schema":{"type":"string","example":"crude_stocks","default":"crude_stocks","title":"Series"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"petroleum_weekly","x-cadence":"Refreshes every 7 days."}}},"components":{"schemas":{"APIKeyCreate":{"properties":{"email":{"type":"string","title":"Email","description":"Where this key belongs. Agents: your human's real address, else your own mailbox.","example":"owner@yourcompany.com"}},"type":"object","required":["email"],"title":"APIKeyCreate"},"AgentSubscribeRequest":{"properties":{"plan":{"type":"string","title":"Plan","description":"pass_1h, pass_1d or pass_7d","example":"pass_1d"}},"type":"object","required":["plan"],"title":"AgentSubscribeRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"servers":[{"url":"https://agentdataapi.com/energy"}],"tags":[{"name":"Grid and energy data","description":"Wholesale power prices, grid demand, generation mix, carbon intensity and cheapest charging windows across NEM, GB, EU and US markets, plus EIA weekly petroleum stocks."}]}