exascale.build
api ↗Connect

Docs → API reference

Power Interconnection Queue (ERCOT) API v1

Generated from core.contract.describe_power_interconnection_queue_ercot_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": [
      "capacity_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:

{
  "records": [
    "source_record_count"
  ],
  "requested_mw": [
    "capacity_mw"
  ]
}

Response summary fields:

Accepted fact policy:

Metric metadata:

Metric Category Unit Aggregation Additive Across Groups Authoritative Total Definition
capacity_mw requested_mw MW sum true summary.totals.capacity_mw The project's requested interconnection capacity in MW, as ERCOT reports it (Capacity (MW) on the active sheets, MW ** on the withdrawal sheets).
source_record_count records count count source records true summary.totals.source_record_count Count of ERCOT GIS queue rows in the current result scope (one atom = one INR row of an in-scope sheet).

Rollup rules:

Detail record fields returned when include_records is true:

Row-level citation fields:

Aggregate citation fields:

Codebooks

Field Coverage Codes Examples Note
application_status the lifecycle states served from the ERCOT snapshot 3 ACTIVE = Active — a live request still in the queue (Large/Small Gen sheets; requested, not built), INACTIVE = Inactive — recently went inactive (Inactive Projects sheet), CANCELLED = Cancelled — recently cancelled (Cancellation Update sheet) ALWAYS scope by application_status. ACTIVE = the live request pipeline (the Large/Small Gen sheets); INACTIVE / CANCELLED = projects that recently left the queue (the Inactive Projects / Cancellation Update sheets — these list RECENT departures, NOT the full historical withdrawn set). A queue-MW total is REQUESTED capacity, never built — for built/operating capacity use query_power_capacity_v1. Build progress is SEPARATE (gim_study_phase + dates).
size_category the size classes served from the ERCOT snapshot 2 Large = Large generator, Small = Small generator ERCOT splits the active queue into Large Gen and Small Gen sheets; the withdrawal sheets carry ERCOT's own Size Category value.
fuel the distinct fuel codes served from the ERCOT snapshot 13 BIO = Biomass, COA = Coal, GAS = Gas, GEO = Geothermal, HYD = Hydrogen (NOT hydro — hydro is WAT) ERCOT's own fuel codes on the active sheets. NOTE: a battery / storage project carries OTH (fuel) + BA (technology) — there is no BAT fuel code in the standard legend (a one-month 2025-07 BAT anomaly aside). HYD is HYDROGEN, not hydro — hydro is WAT. On the Inactive / Cancellation sheets Fuel is FREE TEXT (e.g. 'Wind', 'Solar', 'Battery Storage'), not a code — served verbatim. Filter by ERCOT's EXACT value.
technology the distinct technology codes served from the ERCOT snapshot 14 BA = Battery Energy Storage, CC = Combined-Cycle, CE = Compressed-Air Energy Storage, CP = Concentrated Solar Power, EN = Energy Storage ERCOT's own technology codes on the active sheets (the (Fuel, Technology) pair defines the resource — e.g. SOL/PV solar, OTH/BA battery, GAS/CC combined-cycle, WIN/WT wind). Filter by ERCOT's EXACT code.
cdr_reporting_zone the distinct zones served from the ERCOT snapshot 7 NORTH = North, SOUTH = South, WEST = West, COASTAL = Coastal, HOUSTON = Houston ERCOT's CDR (Capacity, Demand and Reserves) reporting zone. Filter by ERCOT's EXACT value.
gim_study_phase the distinct GIM Study Phase strings served from the ERCOT snapshot 0 ERCOT's build-progress signal — a COMMA-JOINED string of study-milestone tokens, e.g. 'SS Completed, FIS Completed, IA' (Screening Study completed, Full Interconnection Study completed, Interconnection Agreement) or 'SS Completed, FIS Started, No IA'. Served VERBATIM (never collapsed into a maturity score); the individual milestone DATE columns carry the same progression structurally. SS = Security Screening Study, FIS = Full Interconnection Study, IA = Interconnection Agreement. Filter by ERCOT's EXACT string.

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

Checked Examples

Agent question Request params Checked output
How much requested capacity and how many rows sit in the ERCOT queue, by lifecycle status? {"group_by": ["application_status"]} ercot-queue-by-status.json
What fuels lead ERCOT's active interconnection requests, by requested MW? {"application_status": "ACTIVE", "group_by": ["fuel"], "order_by": "capacity_mw", "top_n": 5} active-by-fuel.json
Which ERCOT CDR reporting zones have the most active requested capacity? {"application_status": "ACTIVE", "group_by": ["cdr_reporting_zone"], "order_by": "capacity_mw"} active-mw-by-zone.json
Return one active ERCOT queue project with a row-level citation. {"application_status": "ACTIVE", "include_records": true, "limit": 1} queue-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.interconnection_queue_ercot.
  2. Call describe_power_interconnection_queue_ercot_v1 to inspect valid filters, groupings, metrics, and citation fields.
  3. Call query_power_interconnection_queue_ercot_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 ↗