API REFERENCE

The buildout, as your agent calls it.

An agent-first, source-cited data layer for the US buildout. Two transports, one contract — call it from MCP or REST and get identical, cited JSON. The authoritative, machine-readable reference is always the live /v1/capabilities and each tool's describe schema.

The loop

Designed so an agent never has to guess:

• discover — list_capabilities lists every data point + how they join (anchors).
• describe — each tool's schema returns its exact filters, group-bys, measures, and what it does not answer.
• query — filters + group_by + server-side order_by/top_n → cited rows + summary.
• verify — get_source_evidence re-opens the raw file, re-hashes it (SHA-256), and returns the literal source cell.

Two surfaces, one contract

Point an agent at the discovery card and it gets the whole map — endpoints, capabilities, and auth posture — in one GET.

Capabilities

Twenty-six live data points plus the capacity-factor compound — each cited to its source file and joinable where the source provides shared anchors (county_fips, state, balancing_authority_code, eia_plant_id). The always-current machine-readable list is /v1/capabilities.

A query, and what comes back

curl -X POST https://api.exascale.build/v1/power/capacity/query \
  -H 'content-type: application/json' \
  -d '{"group_by":["state"],"order_by":"nameplate_mw","top_n":3}'

{
  "as_of": "2026-04-01",
  "summary": { "group_count": 51, "totals": { "nameplate_mw": 1392666.4 } },
  "rows": [
    { "group": {"state":"TX"}, "metrics": {"nameplate_mw": 200429.4},
      "lineage": {"citation_ref": "c1"} }
  ],
  "citations": { "c1": { "source_rows_count": 2437,
    "verify": { "source_id":"energy.eia.eia860m", "source_file":"april_generator2026.xlsx",
                "sheet":"Operating", "source_row":26, "raw_file_sha256":"ec15…",
                "as_of":"2026-04-01" } } }
}

Pass that verify object to /v1/evidence/source-row and the response includes "hash_verified": true with the literal row values — proof, in one call.

Honesty by design

Each tool declares what it won't answer (e.g. capacity is MW, not generation MWh), so your agent declines out-of-scope questions instead of fabricating. Results also carry scope notes on known traps (cumulative vs. flow, region scope, signed measures). Defaults are sensible (current operating fleet, US-only) and never gate what you can reach.

Troubleshooting

Errors are designed to tell an agent what to do next, not just fail:

• 429 — rate limited. You hit a fair-use limit; the response includes retry_after (seconds). Back off and retry.
• 400 — invalid query. The error names the offending parameter and the allowed values; call the tool's describe/schema for valid filters, group-bys, and measures.
• Empty result. Your filters matched no rows — widen them, or check the data point's scope in describe. Defaults are the current operating fleet, US-only.
• Evidence won't verify. A raw_hash_mismatch or citation_not_served error means the snapshot was superseded — re-query for the current as_of and pass the fresh verify handle.
• Connection / health. Endpoint is https://api.exascale.build/mcp (streamable HTTP). Latest-snapshot evaluation is available without a key; identified and historical access uses Authorization: Bearer <key>. Health check: GET https://api.exascale.build/v1/health.

Still stuck? Email info@exascaledata.net.

Connect your agent → · Terms · Privacy