API reference

Quickstart

The Vatio API is REST over HTTPS; every response is JSON (CSV on history endpoints). One uniform shape covers all seven US grids — swap the {iso} path segment. The base URL is http://localhost:8000. Grab your API key from the dashboard, then send it on every request as the X-API-Key header.

# get your free key from the dashboard, then pull the latest SP15 price
$ curl http://localhost:8000/v1/caiso/lmp/realtime?hub=SP15 \
    -H "X-API-Key: vt_live_…"

The machine-readable schema is at /openapi.json.

Authentication

Every request is authenticated with your secret API key, sent as the X-API-Key header:

X-API-Key: vt_live_…

Create, reveal and revoke keys in your dashboard — each key is shown once, so store it securely. Keep it secret: anyone with your key can spend your quota.

Plans & limits

Your plan controls four things: how many calls per month, requests per second, how fresh the data is (free is 15-minutes delayed; paid is live), and how far back history goes. See pricing.

Track your month-to-date usage any time in your dashboard.

Errors & rate limits

Standard HTTP status codes; the body is always {"detail": "…"}. Exceed your per-second rate and you'll get 429 — back off and retry.

Grids & coverage

Every data endpoint is the same shape across grids — just swap the {iso} path segment. Authenticate with your API key (X-API-Key). Timestamps are UTC; prices are $/MWh, power is MW. Free callers see data ≥ 15 min old.

Demand and the full fuel mix are live for all seven grids (hourly, via EIA-930). Prices are CAISO-only today (5-minute, via OASIS) and roll out to the other grids one at a time — price endpoints return 404 for grids that aren't wired yet. Hubs per grid are listed by /v1/public/isos.

Prices (LMP)

$ curl http://localhost:8000/v1/caiso/lmp/realtime?hub=SP15 \
    -H "X-API-Key: vt_live_…"

{ "iso": "caiso", "hub": "SP15", "market": "RTD", "interval_start": "2026-06-27T18:05:00Z", "price": -15.63, "unit": "$/MWh" }

{ "iso": "caiso", "hub": "SP15", "market": "RTD", "unit": "$/MWh", "delayed_minutes": 0, "count": 2,
  "data": [
    { "interval_start": "2026-06-27T18:20:00Z", "price": -16.71 },
    { "interval_start": "2026-06-27T18:25:00Z", "price": -17.04 }
  ] }

Demand

{ "iso": "ercot", "interval_start": "2026-06-27T18:00:00Z", "actual_mw": 67160.0, "forecast_mw": 66890.0, "unit": "MW" }

{ "iso": "ercot", "unit": "MW", "delayed_minutes": 0, "count": 168,
  "data": [ { "interval_start": "2026-06-27T17:00:00Z", "actual_mw": 66740.0, "forecast_mw": 66510.0 } ] }

Generation (fuel mix)

Generation by fuel type, in MW — the full mix (gas, nuclear, coal, hydro, wind, solar, battery, oil, other). Hourly for every grid.

{ "iso": "ercot", "interval_start": "2026-06-27T16:00:00Z",
  "mix": { "nuclear": 4900, "coal": 8200, "gas": 38000, "wind": 9100, "solar": 14500, "battery": 1200, "other": 600 },
  "total_mw": 76500, "unit": "MW" }

{ "iso": "ercot", "fuels": ["nuclear","coal","gas","wind","solar","battery","other"], "unit": "MW", "delayed_minutes": 0, "count": 24,
  "data": [ { "interval_start": "2026-06-27T15:00:00Z", "mix": { "gas": 37500, "wind": 9400, "solar": 15200 } } ] }

Renewables (solar + wind)

A convenience view of the two variable renewables, derived from the fuel mix.

{ "iso": "caiso", "interval_start": "2026-06-27T18:05:00Z", "solar_mw": 19672.0, "wind_mw": 3261.0, "unit": "MW" }

Output formats

All responses are JSON by default. Every */history endpoint also accepts ?format=csv for a download that drops straight into pandas or a spreadsheet:

$ curl http://localhost:8000/v1/ercot/generation/history?format=csv \
    -H "X-API-Key: vt_live_…" -o ercot_generation.csv

CSV columns mirror the JSON fields (for fuel mix, one column per fuel).

Preview endpoints (no key)

These power the public live dashboard and landing demo. They're 15-minute delayed and need no key — handy for a quick look before you sign up.

Get your free key →