exascale.build
api ↗Connect

Docs → API reference

Power Demand (national / region rollup) API v1

Generated from core.contract.describe_power_demand_rollup_v1() and checked fixture-backed examples. Do not hand-edit the example JSON files.

Capability

What It Can Answer

Represented Facts

Data Point Contract

Does not answer:

REST Surface

MCP Surface

Local MCP Setup

Some MCP clients launch servers from the user's home directory or ignore a configured cwd. Use uv run --directory so the server always starts from the repository project.

{
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "/absolute/path/to/OSINT",
    "python",
    "-m",
    "core.mcp_server"
  ]
}

Leave EXASCALE_PARQUET_BASE / EXASCALE_RAW_BASE unset: the one server hosts every data point's tools, and with no override it resolves each block's promoted snapshots and raw archive from the repository layout. Setting either env var points ALL tools at one directory — a per-block path breaks every other block's tools. They exist only for single-source sandboxes and tests.

Request Schema

Filters:

Group by:

Date range parameters:

Controls:

Ranking (how order_by / top_n / order join — order_by ranks groups by a metric, never a group_by dimension; top_n needs both a group_by and an order_by):

{
  "no_ranking": "Omit order_by and top_n to return all groups in group-key order.",
  "order": {
    "default": "desc",
    "valid_values": [
      "desc",
      "asc"
    ]
  },
  "order_by": {
    "accepts": "one of output.metrics",
    "note": "Ranks the groups by a metric (a measure). Not a group_by dimension \u2014 rows already come back grouped by each group_by field.",
    "requires": [
      "group_by"
    ],
    "valid_values": [
      "demand_mw",
      "demand_forecast_mw",
      "source_record_count"
    ]
  },
  "top_n": {
    "note": "Keeps the top N groups by order_by; the rest fold into one (other) remainder (additive metrics sum into it, non-additive ones are nulled) so the result still reconciles to summary.totals.",
    "requires": [
      "group_by",
      "order_by"
    ],
    "type": "positive integer"
  }
}

Output Schema

Aggregate metrics:

Metric groups:

{
  "demand_mw": [
    "demand_mw",
    "demand_forecast_mw"
  ],
  "records": [
    "source_record_count"
  ]
}

Response summary fields:

Accepted fact policy:

Metric metadata:

Metric Category Unit Aggregation Additive Across Groups Authoritative Total Definition
demand_mw demand_mw MW sum false summary.totals.demand_mw EIA's published hourly demand total (MW, Adjusted series) for the respondent in scope — US48 (the Lower-48 national total) or one of the 13 EIA regions.
demand_forecast_mw demand_mw MW sum false summary.totals.demand_forecast_mw EIA's published day-ahead hourly demand forecast (MW) for the same respondent-hour.
source_record_count records count count source records true summary.totals.source_record_count Count of normalized source records (respondent-hours) contributing to the current result scope.

Rollup rules:

Detail record fields returned when include_records is true:

Row-level citation fields:

Aggregate citation fields:

Codebooks

Field Coverage Codes Examples Note
respondent complete_for_gated_eia930_rollup_rows 14 CAL = California, CAR = Carolinas, CENT = Central, FLA = Florida, MIDA = Mid-Atlantic EIA's published demand respondents: US48 (the Lower-48 national total) and the 13 EIA regions. demand_mw is already each respondent's published total, so summing across respondents double-counts (US48 contains the 13 regions) — group_by respondent for the per-respondent series; a multi-respondent result carries a respondent_aggregation note. An EIA region is a grid grouping, not a state. A region named like a state is not guaranteed to equal it: TEX ('Texas') is the ERCOT grid alone — ~90% of Texas load — while non-ERCOT El Paso, the Panhandle, and East Texas fall in OTHER EIA regions. Some regions span several states (NE = New England's six; CAR = the Carolinas; MIDA ≈ the PJM footprint); others nearly match their namesake (NY ≈ New York via NYISO). Use respondent for a region/grid total and a state-grain source (power.retail_sales) for a jurisdiction. When a phrase like 'Texas demand' is ambiguous between the EIA region and the state, report both readings rather than guessing (PD-035).

The complete machine-readable codebooks are included in capability-schema.json.

Checked Examples

Agent question Request params Checked output
What was the US48 national hourly demand on 2026-06-10? {"data_date": "2026-06-10", "group_by": ["datetime_utc"], "respondent": "US48"} us48-national-demand-curve.json
How does hourly demand compare across EIA regions on 2026-06-10? {"data_date": "2026-06-10", "group_by": ["respondent", "datetime_utc"]} demand-by-region.json
How did the US48 day-ahead forecast compare to actual demand, hour by hour, on 2026-06-10? {"data_date": "2026-06-10", "group_by": ["hour_number"], "respondent": "US48"} forecast-vs-actual-national.json
Return one US48 demand record with a row-level citation. {"data_date": "2026-06-10", "include_records": true, "limit": 1, "respondent": "US48"} region-detail-with-citation.json
Verify the raw workbook row behind a returned citation citations[ref].verify (aggregate) or records[0].citation (detail) source-row-evidence.json
Dogfood the tool sequence as an agent list -> describe -> query -> evidence agent-dogfood-transcript.json

The checked schema output is capability-schema.json.

Agent Workflow

  1. Call list_capabilities_v1 and select power.demand_rollup.
  2. Call describe_power_demand_rollup_v1 to inspect valid filters, groupings, metrics, and citation fields.
  3. Call query_power_demand_rollup_v1 with bounded JSON params.
  4. If the answer needs proof, pass a returned row-level citation object to get_source_evidence_v1.
  5. Answer with the resolved as_of and relevant citations. Present returned metrics as authoritative for their declared source, snapshot, grain, and aggregation.
Generated from the tested API contract. Compare with the live capability map ↗