exascale.build
api ↗Connect

Docs → API reference

Power Capacity API v1

Generated from core.contract.describe_power_capacity_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:

Input field semantics:

Field Answer Label Source Field Semantics Definition Counting Definition
state state/jurisdiction Plant State source_reported_eia860m_plant_state_or_jurisdiction_code The EIA-860M Plant State value for the generator's plant. Values are two-letter U.S. state, District of Columbia, or territory/jurisdiction codes when present. A count of grouped state values is a count of state-level jurisdiction codes, not a count of U.S. states; 51 values can mean 50 states plus DC.

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": [
      "nameplate_mw",
      "net_summer_mw",
      "net_winter_mw",
      "generator_count",
      "distinct_plant_count",
      "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"
  }
}

Canonical filters:

{
  "battery_storage": {
    "description": "Planned, operating, retired, or canceled battery storage capacity represented by this primitive.",
    "energy_capacity_policy": "`nameplate_energy_mwh` is only represented when the source row provides it. Do not derive MWh from MW unless the answer clearly labels the duration assumption outside exascale represented facts.",
    "params": {
      "technology": "Batteries"
    },
    "scope_note": "Use `technology = Batteries` as the user-facing canonical battery storage filter. `prime_mover_code = BA` and `energy_source_code = MWH` remain valid source-coded filters and may return different scopes.",
    "source_semantics": {
      "energy_source_code": "MWH",
      "prime_mover_code": "BA",
      "technology": "Batteries"
    }
  }
}

Output Schema

Aggregate metrics:

Metric groups:

{
  "capacity_mw": [
    "nameplate_mw",
    "net_summer_mw",
    "net_winter_mw"
  ],
  "entities": [
    "distinct_plant_count"
  ],
  "records": [
    "generator_count",
    "source_record_count"
  ]
}

Response summary fields:

Accepted fact policy:

Metric metadata:

Metric Category Unit Aggregation Additive Across Groups Authoritative Total Definition
nameplate_mw capacity_mw MW sum true summary.totals.nameplate_mw Sum of EIA-reported generator nameplate capacity within the current result scope.
net_summer_mw capacity_mw MW sum true summary.totals.net_summer_mw Sum of EIA-reported generator net summer capacity within the current result scope.
net_winter_mw capacity_mw MW sum true summary.totals.net_winter_mw Sum of EIA-reported generator net winter capacity within the current result scope.
generator_count records count count source records true summary.totals.generator_count Count of normalized generator records within the current result scope.
distinct_plant_count entities count count_distinct false summary.totals.distinct_plant_count Count of distinct EIA plant IDs within the current result scope.
source_record_count records count count source records true summary.totals.source_record_count Count of normalized source rows 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
energy_source_code complete_for_validated_eia860m_energy_source_codes 39 AB = Agricultural By-Products, ANT = Anthracite Coal, BFG = Blast Furnace Gas, BIT = Bituminous Coal, BLQ = Black Liquor
prime_mover_code complete_for_validated_eia860m_prime_mover_codes 23 BA = Energy Storage, Battery, BT = Turbines Used in a Binary Cycle (including those used for geothermal applications), CA = Combined Cycle Steam Part, CC = Combined Cycle Total Unit (use only for plants/generators that are in planning stage, for which specific generator details cannot be provided), CE = Energy Storage, Compressed Air
status_code lifecycle_specific 11 operating.OA = Out of service but expected to return to service in next calendar year, operating.OP = Operating, planned.L = Regulatory approvals pending. Not under construction, planned.OT = Other
balancing_authority_code partial_for_eia860m 81 AEC = PowerSouth Energy Cooperative, AECI = Associated Electric Cooperative, Inc., AESO = Alberta Electric System Operator, AVA = Avista Corporation, AVRN = Avangrid Renewables, LLC EIA-860M reports this BA code on the generator row. exascale.build preserves it as source-reported data; it is not an independently validated physical BA-footprint assignment or corrected grid-operator attribution. EIA-860M can emit BA codes outside the EIA-930 reference table; missing labels are preserved as source-reported codes. A balancing authority is not a state. ERCO (ERCOT) lies wholly within Texas and covers ~90% of its load, but state=TX is the larger jurisdiction — it also includes non-ERCOT El Paso (WECC), the Panhandle (SPP), and East Texas (MISO), a material (~20%+) difference. Use balancing_authority_code for a grid and state for a jurisdiction; they are not interchangeable. When a phrase like 'the Texas grid' is ambiguous between the two, report both readings rather than guessing one (PD-009).

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

Checked Examples

Agent question Request params Checked output
What operating capacity exists by county in Alabama? {"group_by": ["county_fips"], "lifecycle": "operating", "state": "AL"} operating-capacity-by-county.json
What planned capacity exists by state/jurisdiction and fuel for Texas and Arizona? {"group_by": ["state", "energy_source_code"], "lifecycle": "planned", "state": ["TX", "AZ"]} planned-capacity-by-state-and-fuel.json
What planned Texas capacity is reported by source-reported balancing authority code? {"group_by": ["balancing_authority_code"], "lifecycle": "planned", "state": "TX"} planned-capacity-by-balancing-authority.json
What retired capacity is reported by retirement year? {"group_by": ["retirement_year"], "lifecycle": "retired"} retired-capacity-by-year.json
Return one planned Texas generator with a row-level citation. {"include_records": true, "lifecycle": "planned", "limit": 1, "state": "TX"} generator-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.capacity.
  2. Call describe_power_capacity_v1 to inspect valid filters, groupings, metrics, and citation fields.
  3. Call query_power_capacity_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 ↗