Developer Reference

API Documentation

Complete reference for the Energy API — electricity, gas, coal, carbon, and carbon intensity prices.

Sections

Introduction

Energy API aggregates price data from official exchanges and agencies — OMIE, ENTSO-E, Energy-Charts, ESIOS, US ISOs, AEMO, EIA, FRED, Ember — and normalizes it under a single REST interface. Query by symbol for full flexibility, or use category endpoints for common product workflows.

The API exposes 16 endpoints: six generic symbol-based routes (/latest, /timeseries, …) plus ten category endpoints for electricity intraday curves, gas/coal/emissions shortcuts, carbon intensity, day-ahead forecasts, cost estimates, and provider status.

Data update frequency follows each source's publication schedule (see GET /status). The dates field in responses shows the exact observation date per symbol.

Base URL

https://energy-api.com/api/v1

Authentication

All requests must include your API key using the api_key query parameter (header auth such as Authorization: Bearer is not supported).

Replace YOUR_API_KEY with your actual key from your dashboard.

Try in your browser

https://energy-api.com/api/v1/latest?symbols=EPEX_DE_DA,TTF_GAS&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/latest \
  --data-urlencode "symbols=EPEX_DE_DA,TTF_GAS" \
  --data-urlencode "api_key=YOUR_API_KEY"

Keep your API key secret. Never expose it in client-side JavaScript or public repositories. If a key is compromised, rotate it immediately from the dashboard.

Symbol Model

Every price is identified by a normalized symbol — a stable string like EPEX_DE_DA or OMIE_ES_DA. Symbols are grouped into these categories:

Electricity category=electricity

Day-ahead and spot power prices across European and global markets.

Gas category=gas

Natural gas benchmarks for EU and US wholesale markets, plus weekly US storage.

Oil category=oil

Weekly US crude, Cushing, gasoline and distillate stocks from EIA.

Coal category=coal

Thermal coal benchmarks for Atlantic and Pacific basins.

Carbon category=carbon

EU ETS carbon allowance (EUA) reference prices.

Carbon Intensity category=carbon_intensity

Grid emissions intensity in gCO₂eq/kWh for the EU electricity mix.

Use GET /symbols to list all active symbols with metadata. Pass category or base to filter. The base parameter filters by currency code (e.g. base=EUR returns all EUR-denominated symbols).

Not every symbol is a price. Weekly EIA stocks sit next to the prices they move — GAS_STORAGE_US_L48 (Bcf) in gas, CRUDE_STOCKS_US, CRUDE_STOCKS_CUSHING, gasoline and distillate stocks (kbbl) in oil, dated by EIA's week-ending Friday — and category=load holds ENTSO-E actual load (MW, daily average) for each zone with a day-ahead price. These have no currency: read the unit field of each symbol.

Validation note: if base does not match a supported active currency code, the API returns 422.

GET /symbols

Discover all available energy price symbols with their metadata. Use this endpoint to build dynamic symbol pickers or validate that a symbol exists before querying other endpoints.

Parameters

Param Type Required Description
basestring (3)optionalFilter rates by currency code. Must be a supported active currency code; otherwise returns 422.
categorystringoptionalOne of: gas, electricity, oil, coal, carbon, carbon_intensity, load. Invalid values return 422.
providerstringoptionalOne of: aemo, eia, ember, energy_charts, entsoe, esios, fred, gridstatus, omie. Only sources with at least one listed symbol are accepted; anything else returns 422 including the allowed list.

Example request

Try in your browser

https://energy-api.com/api/v1/symbols?category=gas&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/symbols \
  --data-urlencode "category=gas" \
  --data-urlencode "api_key=YOUR_API_KEY"

Response

{
  "success": true,
  "count": 3,
  "symbols": [
    {
      "symbol":        "TTF_GAS",
      "name":          "TTF Natural Gas Price, Monthly Average (IMF)",
      "category":      "gas",
      "country_code":  "EU",
      "currency_code": "USD",
      "provider":      "fred",
      "frequency":     "monthly",
      "unit":          "USD/MMBtu",
      "description":   "European natural gas price (Netherlands TTF), monthly average. Units: USD per million Btu (IMF PNGASEUUSDM via FRED). Not a daily hub price."
    },
    {
      "symbol":        "HENRY_HUB",
      "name":          "Henry Hub Natural Gas Spot Price",
      "category":      "gas",
      "country_code":  "US",
      "currency_code": "USD",
      "provider":      "eia",
      "frequency":     "daily",
      "unit":          "USD/MMBtu",
      "description":   "Henry Hub spot price for natural gas in USD/MMBtu. Published by EIA/FRED."
    }
    // ... more symbols
  ]
}
GET /latest

Returns the most recent available value for each requested symbol.

Parameters

Param Type Required Description
symbolsstringrequiredComma-separated symbol names. E.g. EPEX_DE_DA,TTF_GAS,EUA_CO2.
basestring (3)optionalFilter by currency code. Must be a supported active currency code; otherwise returns 422.
categorystringoptionalFilter by category. One of: gas, electricity, oil, coal, carbon, carbon_intensity, load.

Example request

Try in your browser

https://energy-api.com/api/v1/latest?symbols=EPEX_DE_DA,TTF_GAS,EUA_CO2,OMIE_ES_DA&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/latest \
  --data-urlencode "symbols=EPEX_DE_DA,TTF_GAS,EUA_CO2,OMIE_ES_DA" \
  --data-urlencode "api_key=YOUR_API_KEY"

Response

{
  "success": true,
  "date":    "2026-10-21",
  "base":    "MIXED",
  "rates": {
    "EPEX_DE_DA":  211.9377,
    "TTF_GAS":     25.494,
    "EUA_CO2":     78.82,
    "OMIE_ES_DA":  146.9661
  },
  "dates": {
    "EPEX_DE_DA":  "2026-10-21",
    "TTF_GAS":     "2026-09-01",
    "EUA_CO2":     "2026-10-01",
    "OMIE_ES_DA":  "2026-10-21"
  },
  "currencies": {
    "EPEX_DE_DA":  "EUR",
    "TTF_GAS":     "USD",
    "EUA_CO2":     "EUR",
    "OMIE_ES_DA":  "EUR"
  },
  "base_filter_note": null,
  "missing_symbols":  null
}
Each symbol keeps its own frequency: TTF_GAS (IMF monthly average, USD/MMBtu) and EUA_CO2 (ESIOS monthly reference) are dated the first of their month, so their dates trail the day-ahead electricity prices.
missing_symbols: every requested symbol the response leaves out, with the reason: unknown (not in the catalog), unlisted (taken off it), base_mismatch / category_mismatch (excluded by your filter) or no_data (no value for the request). null when everything came back. Also returned by /historical, /timeseries, /fluctuation and /ohlc.
Important: if you pass base, symbols with a different currency code are excluded. For example, with base=USD, EUR-denominated symbols like OMIE_ES_DA or EUA_CO2 will not be returned.
The top-level date is the most recent date across all returned prices. Use the dates object to see the exact observation date per symbol — energy markets generally publish daily on business days.
GET /historical

Returns values for all requested symbols on a specific date. If a symbol does not publish on the exact date requested (e.g., weekend), the API returns the most recent available value before that date.

Parameters

Param Type Required Description
datedate (YYYY-MM-DD)requiredThe date to query.
symbolsstringrequiredComma-separated symbol names.
basestring (3)optionalFilter rates by currency code. Must be a supported active currency code; otherwise returns 422.

Example request

Try in your browser

https://energy-api.com/api/v1/historical?date=2025-09-15&symbols=EPEX_DE_DA,TTF_GAS&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/historical \
  --data-urlencode "date=2025-09-15" \
  --data-urlencode "symbols=EPEX_DE_DA,TTF_GAS" \
  --data-urlencode "api_key=YOUR_API_KEY"

Response

{
  "success": true,
  "date":    "2025-09-15",
  "base":    "MIXED",
  "rates": {
    "EPEX_DE_DA":  8.8308,
    "TTF_GAS":     11.003
  },
  "dates": {
    "EPEX_DE_DA":  "2025-09-15",
    "TTF_GAS":     "2025-09-01"
  },
  "currencies": {
    "EPEX_DE_DA":  "EUR",
    "TTF_GAS":     "USD"
  },
  "base_filter_note": null,
  "missing_symbols":  null
}
Date alignment note: the top-level date echoes your requested date as-is. The per-symbol dates map shows the date each value actually came from — it may differ from the requested date on a non-publishing day (weekend/holiday) or for monthly/weekly symbols.
GET /timeseries

Returns all observations for the requested symbols between start and end, keyed by date. Ideal for charting and trend analysis.

Parameters

Param Type Required Description
startdate (YYYY-MM-DD)requiredStart date (inclusive).
enddate (YYYY-MM-DD)requiredEnd date (inclusive). Must be ≥ start.
symbolsstringrequiredComma-separated symbol names.
basestring (3)optionalFilter rates by currency code. Must be a supported active currency code; otherwise returns 422.

Example request

Try in your browser

https://energy-api.com/api/v1/timeseries?start=2025-01-01&end=2025-03-31&symbols=EPEX_DE_DA,TTF_GAS&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/timeseries \
  --data-urlencode "start=2025-01-01" \
  --data-urlencode "end=2025-03-31" \
  --data-urlencode "symbols=EPEX_DE_DA,TTF_GAS" \
  --data-urlencode "api_key=YOUR_API_KEY"

Response

{
  "success":    true,
  "base":       "MIXED",
  "start_date": "2025-01-01",
  "end_date":   "2025-03-31",
  "rates": {
    "EPEX_DE_DA":  {
      "2025-01-01": 0.9546,
      "2025-01-02": 92.9096,
      "2025-01-03": 89.9408
      // ... daily observations
    },
    "TTF_GAS": {
      "2025-01-01": 14.759096,
      "2025-02-01": 15.376383,
      "2025-03-01": 13.15601
    }
  },
  "frequencies": {
    "EPEX_DE_DA":  "daily",
    "TTF_GAS":     "monthly"
  },
  "currencies": {
    "EPEX_DE_DA":  "EUR",
    "TTF_GAS":     "USD"
  },
  "base_filter_note": null,
  "missing_symbols":  null
}
GET /fluctuation

Returns the start value, end value, absolute change, and percentage change for each symbol over the requested period. Calculations use the first and last available observations inside the requested range (not synthetic values for missing days).

Parameters

Param Type Required Description
startdate (YYYY-MM-DD)requiredStart date of the period.
enddate (YYYY-MM-DD)requiredEnd date of the period.
symbolsstringrequiredComma-separated symbol names.
basestring (3)optionalFilter rates by currency code. Must be a supported active currency code; otherwise returns 422.

Example request

Try in your browser

https://energy-api.com/api/v1/fluctuation?start=2025-07-01&end=2025-12-31&symbols=EPEX_DE_DA,EUA_CO2&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/fluctuation \
  --data-urlencode "start=2025-07-01" \
  --data-urlencode "end=2025-12-31" \
  --data-urlencode "symbols=EPEX_DE_DA,EUA_CO2" \
  --data-urlencode "api_key=YOUR_API_KEY"

Response

{
  "success":    true,
  "base":       "EUR",
  "start_date": "2025-07-01",
  "end_date":   "2025-12-31",
  "rates": {
    "EPEX_DE_DA":  {
      "start_date":  "2025-07-01",
      "end_date":    "2025-12-31",
      "start_value": 138.3646,
      "end_value":   87.3138,
      "change":      -51.0508,
      "change_pct":  -36.8959,
      "high":        220.517,
      "low":         -0.2911
    },
    "EUA_CO2": {
      "start_date":  "2025-07-01",
      "end_date":    "2025-12-01",
      "start_value": 68.965,
      "end_value":   72.662,
      "change":      3.697,
      "change_pct":  5.3607,
      "high":        72.662,
      "low":         68.965
    }
  },
  "currencies": {
    "EPEX_DE_DA":  "EUR",
    "EUA_CO2":     "EUR"
  },
  "base_filter_note": null,
  "missing_symbols":  null
}
Date alignment note: the top-level start_date/end_date echo your requested range as-is. The per-symbol start_date/end_date reflect the first and last dates that symbol actually published inside that range, so they may differ from the requested boundary on a non-publishing day (holiday/weekend/provider gap).
Why this happens: providers do not publish every calendar day. Most series are business-day only (no weekends/holidays), and some symbols are monthly or weekly by definition. The endpoint therefore computes fluctuation from the first and last available observations inside the requested window.
GET /ohlc

Returns open/high/low/close aggregates for each symbol over weekly, monthly, or quarterly periods. Designed for charting libraries and volatility analysis dashboards.

Parameters

Param Type Required Description
symbolsstringrequiredComma-separated symbol names.
periodstringoptionalOne of: weekly, monthly (default), quarterly.
startdate (YYYY-MM-DD)optionalStart date. Defaults to 1 year ago.
enddate (YYYY-MM-DD)optionalEnd date. Defaults to today.
basestring (3)optionalFilter rates by currency code. Must be a supported active currency code; otherwise returns 422.

Example request

Try in your browser

https://energy-api.com/api/v1/ohlc?symbols=EPEX_DE_DA&period=monthly&start=2025-01-01&end=2025-06-30&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/ohlc \
  --data-urlencode "symbols=EPEX_DE_DA" \
  --data-urlencode "period=monthly" \
  --data-urlencode "start=2025-01-01" \
  --data-urlencode "end=2025-06-30" \
  --data-urlencode "api_key=YOUR_API_KEY"

Response

{
  "success":    true,
  "period":     "monthly",
  "start_date": "2025-01-01",
  "end_date":   "2025-06-30",
  "rates": {
    "EPEX_DE_DA":  [
      {
        "period":      "2025-01",
        "open":        76.30,
        "high":        80.15,
        "low":         73.20,
        "close":       78.40,
        "data_points": 31
      },
      {
        "period":      "2025-02",
        "open":        78.40,
        "high":        79.80,
        "low":         72.50,
        "close":       74.90,
        "data_points": 28
      }
      // ... more periods
    ]
  }
}

Category Endpoints

Higher-level endpoints shaped for common product use cases. Same authentication, quotas, and rate limits as the generic symbol endpoints above.

GET /electricity/latest

Electricity Latest

Returns the latest electricity prices for all active electricity symbols. Optional country filter (ISO-2). Response shape matches GET /latest.

Parameters

Name Type Required Description
country string optional ISO-2 country code, e.g. ES, DE, FR.
base string optional Filter by currency code (EUR, USD, …).

Example request

Try in your browser

https://energy-api.com/api/v1/electricity/latest?country=ES&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/electricity/latest \
  --data-urlencode "country=ES" \
  --data-urlencode "api_key=YOUR_API_KEY"
GET /electricity/hourly

Electricity Hourly (Intraday)

Full intraday price curve for one electricity symbol on a given date. Returns 15-min, hourly, or 5-min points depending on the symbol. Only symbols with has_intraday_storage=true are supported (404 otherwise).

Parameters

Name Type Required Description
symbol string required Electricity symbol, e.g. OMIE_ES_DA, PVPC_ES_2TD.
date date required Calendar date (YYYY-MM-DD).

Example request

Try in your browser

https://energy-api.com/api/v1/electricity/hourly?symbol=OMIE_ES_DA&date=2026-06-18&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/electricity/hourly \
  --data-urlencode "symbol=OMIE_ES_DA" \
  --data-urlencode "date=2026-06-18" \
  --data-urlencode "api_key=YOUR_API_KEY"
GET /electricity/pvpc

PVPC (Spain)

Hourly Spanish PVPC reference prices for a date. Convenience wrapper around PVPC_ES_2TD with friendly field names (hours, price_eur_mwh).

Parameters

Name Type Required Description
date date required Calendar date (YYYY-MM-DD).

Example request

Try in your browser

https://energy-api.com/api/v1/electricity/pvpc?date=2026-06-18&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/electricity/pvpc \
  --data-urlencode "date=2026-06-18" \
  --data-urlencode "api_key=YOUR_API_KEY"
GET /gas/latest

Gas Latest

Latest TTF_GAS (EU, IMF monthly average, USD/MMBtu) and HENRY_HUB (US, daily) prices. NBP, JKM, and AECO are not sourced — they are absent from the response, not returned as null.

Parameters

Name Type Required Description
base string optional Filter by currency code.

Example request

Try in your browser

https://energy-api.com/api/v1/gas/latest?api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/gas/latest \
  --data-urlencode "api_key=YOUR_API_KEY"
GET /emissions/latest

Emissions Latest

Latest EU ETS allowance prices: EUA_CO2 (monthly ESIOS reference, the PCO2D parameter of the Spanish system operator — not an exchange settlement). UK ETS is not currently sourced.

Parameters

Name Type Required Description
base string optional Filter by currency code.

Example request

Try in your browser

https://energy-api.com/api/v1/emissions/latest?api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/emissions/latest \
  --data-urlencode "api_key=YOUR_API_KEY"
GET /coal/latest

Coal Latest

Latest COAL_NEWCASTLE price (IMF monthly average, USD/tonne). Rotterdam API 2 is not currently available; missing_symbols says so in the response.

Parameters

Name Type Required Description
base string optional Filter by currency code.

Example request

Try in your browser

https://energy-api.com/api/v1/coal/latest?api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/coal/latest \
  --data-urlencode "api_key=YOUR_API_KEY"
GET /carbon-intensity

Carbon Intensity

Latest grid carbon intensity values (gCO₂eq/kWh) for carbon_intensity symbols. Today this is the EU-27 monthly average (CARBON_INT_EU, from Ember); country-level series are not currently sourced, so a country filter returns 404.

Parameters

Name Type Required Description
country string optional ISO-2 country code, e.g. ES, DE, GB.
base string optional Pseudo-currency CO2 for intensity symbols.

Example request

Try in your browser

https://energy-api.com/api/v1/carbon-intensity?api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/carbon-intensity \
  --data-urlencode "api_key=YOUR_API_KEY"
GET /forecast

Forecast (Day-Ahead)

Returns the next published day-ahead price for auction-sourced electricity symbols. This is a deterministic lookup of already-published auction results, not a predictive model. Before the next day-ahead price is published, returns the last available one instead — check is_forecast in the response to tell them apart. Returns 404 for monthly symbols (EUA_CO2), non-price series such as actual load (LOAD_*), and providers without day-ahead auctions.

Parameters

Name Type Required Description
symbol string required Day-ahead electricity symbol, e.g. OMIE_ES_DA.

Example request

Try in your browser

https://energy-api.com/api/v1/forecast?symbol=OMIE_ES_DA&api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/forecast \
  --data-urlencode "symbol=OMIE_ES_DA" \
  --data-urlencode "api_key=YOUR_API_KEY"
POST /cost-estimate

Cost Estimate

Simple monthly wholesale electricity cost estimate: latest daily-average price × kWh/month. Does not include taxes, network charges, or hourly usage profiles (see methodology_note in response).

Parameters

Name Type Required Description
symbol string required* Electricity symbol. Required if country is omitted.
country string required* ISO-2 country code. Required if symbol is omitted. When multiple electricity symbols exist for a country (e.g. ES: OMIE_ES_DA + PVPC_ES_2TD), the day-ahead wholesale symbol (*_DA) is preferred. Countries split into several bidding zones (NO, SE, DK, IT, US) return 422 with the matching symbols — pass symbol instead.
kwh_per_month number required Monthly consumption in kWh.

Example request

curl -X POST "https://energy-api.com/api/v1/cost-estimate?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"OMIE_ES_DA","kwh_per_month":250}'
GET /status

Provider Status

Last fetch log entry per data provider — useful for monitoring pipeline health.

Example request

Try in your browser

https://energy-api.com/api/v1/status?api_key=YOUR_API_KEY

Example using cURL

curl -G https://energy-api.com/api/v1/status \
  --data-urlencode "api_key=YOUR_API_KEY"

Retail fuel prices

Pump prices by country, for apps that show drivers what they pay. This is a separate product from the wholesale Symbol Model: there are no symbols, nothing appears in /symbols, and each country answers in its own source's shape, grain and unit — nothing is converted between countries.

  • Base path https://energy-api.com/api/v1/retail, with your usual Energy API key.
  • Professional plan and above (trials of those plans included). Free and Starter receive 403.
  • Each call counts as 1 request, like any other endpoint.
  • If a retail source is down, its endpoints answer 503 with a Retry-After header; the wholesale endpoints and /status are not affected.

Daily pump prices by city and state.

Unit: INR per litre for petrol, diesel and autogas; CNG per kg and LPG per 14.2 kg cylinder.

GET /retail/india/latest

Today’s pump prices for one city.

  • city (required) — City name, e.g. Delhi or Mumbai.
  • state (optional) — State, to tell apart cities with the same name.
https://energy-api.com/api/v1/retail/india/latest?city=Delhi&api_key=YOUR_API_KEY
GET /retail/india/historical

Pump prices for one city on a past date.

  • city (required) — City name.
  • date (required) — YYYY-MM-DD, today or earlier.
  • state (optional) — State, to tell apart cities with the same name.
https://energy-api.com/api/v1/retail/india/historical?city=Delhi&date=2026-10-20&api_key=YOUR_API_KEY
GET /retail/india/states

States covered, with the number of cities in each.

https://energy-api.com/api/v1/retail/india/states?api_key=YOUR_API_KEY
GET /retail/india/cities

Cities covered and the fuels each one reports.

  • state (optional) — Only cities in this state.
  • q (optional) — Search by city name.
  • page (optional) — Page number (default 1).
  • per_page (optional) — Results per page, up to 500 (default 100).
https://energy-api.com/api/v1/retail/india/cities?state=Delhi&api_key=YOUR_API_KEY

United States

US gas prices API →

Prices at individual gas stations, searched by ZIP code.

Unit: USD per gallon.

GET /retail/us/prices

What each station near a ZIP code charges. A ZIP not asked for recently is fetched live and can take up to half a minute; those answers start with the area’s average and lowest price.

  • zip (required) — Five-digit US ZIP code, e.g. 10001.
  • type (optional) — regular (default), mid-grade, premium or diesel.
https://energy-api.com/api/v1/retail/us/prices?zip=10001&type=regular&api_key=YOUR_API_KEY
GET /retail/us/station

One station: address, coordinates, opening hours, fuels, brands and amenities.

  • station_id (required) — The station_id returned by /retail/us/prices.
https://energy-api.com/api/v1/retail/us/station?station_id=56273&api_key=YOUR_API_KEY

European Union

EU fuel prices API →

Weekly national average per country, with and without taxes — not a station price.

Unit: As the bulletin publishes it: EUR per 1000 litres (heavy fuel oil EUR per tonne).

GET /retail/eu/latest

The latest weekly bulletin.

  • country (optional) — Two-letter code (DE, FR, ES...) or EU / EUR for the averages.
https://energy-api.com/api/v1/retail/eu/latest?country=DE&api_key=YOUR_API_KEY
GET /retail/eu/historical

The bulletin in force on a past date (the latest one published on or before it).

  • date (required) — YYYY-MM-DD, from 2005-01-03.
  • country (optional) — Two-letter code or EU / EUR.
https://energy-api.com/api/v1/retail/eu/historical?date=2024-05-13&country=FR&api_key=YOUR_API_KEY

Error Codes

All errors return a consistent JSON payload with success: false and a human-readable error message.

{
  "success": false,
  "error": "No symbols matched the requested base currency (USD). Requested symbol currencies: BANXICO_RATE=MXN."
}
HTTP Code Meaning Common cause
401UnauthorizedMissing or invalid api_key query parameter.
404Not FoundNo data found for the given symbols or date, or the symbol is unknown or off the catalog (the message names unlisted symbols — check /v1/symbols).
422Validation ErrorMissing required parameter, invalid date format, or unsupported value (e.g. unknown category).
429Too Many RequestsPer-minute rate limit exceeded. Back off and retry after a few seconds.

Rate Limits & Quotas

Each plan has a monthly request quota, a per-minute rate limit, and timeseries date-range caps. All endpoints — including POST /cost-estimate — count toward the same monthly quota. Quotas reset on the 1st of each month (UTC). Monitor usage from your dashboard.

• Guest playground (homepage, no account): 3 calls per month.

• Free account: 20 API calls per month after signup (no credit card).

• Paid plan limits below apply once you subscribe or start a trial.

Plan Requests / month Timeseries Req / min
Starter 5,000 1 year 60
Professional 15,000 5 years 120
Business 40,000 Full history 240
Enterprise Custom Full history Custom

• When the per-minute limit is exceeded the API returns HTTP 429. Implement exponential back-off in your client.

• When the monthly quota is exhausted the API returns HTTP 429 until the next billing month or you upgrade.

• Use the symbols parameter to request only what you need — this is the most effective way to reduce quota consumption.

• Need higher volume? Contact us about Business or Enterprise.

Ready to start building?

Get your API key, make your first request in under 2 minutes, and start shipping energy price features today.