exascale.build
api ↗Connect

Docs → API reference

Power Interconnection Queue (NYISO) API v1

Generated from core.contract.describe_power_interconnection_queue_nyiso_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": [
      "sp_mw",
      "wp_mw",
      "peak_mw_load",
      "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:

{
  "load_mw": [
    "peak_mw_load"
  ],
  "records": [
    "source_record_count"
  ],
  "requested_mw": [
    "sp_mw",
    "wp_mw"
  ]
}

Response summary fields:

Accepted fact policy:

Metric metadata:

Metric Category Unit Aggregation Additive Across Groups Authoritative Total Definition
sp_mw requested_mw MW sum true summary.totals.sp_mw The project's maximum summer megawatt output, as NYISO reports it (SP (MW)).
wp_mw requested_mw MW sum true summary.totals.wp_mw The project's maximum winter megawatt output, as NYISO reports it (WP (MW)).
peak_mw_load load_mw MW sum true summary.totals.peak_mw_load The project's requested peak load (Load Projects tab), as NYISO reports it (Peak MW load).
source_record_count records count count source records true summary.totals.source_record_count Count of NYISO queue project-rows in the current result scope (one atom = one row of one lifecycle tab; nine tabs through 2026-06, seven since the 2026-07 restructure).

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 distinct application_status values served from the NYISO snapshot 5 ACTIVE = Active — a live request still in the queue (requested, not built), WITHDRAWN = Withdrawn — the request left the queue (the queue is withdrawn-dominated), IN_SERVICE = In service — the project is built and energized, AFFECTED_SYSTEM = Affected-system study — an out-of-NYISO project studied for NY-system impact, AFFECTED_SYSTEM_WITHDRAWN = Withdrawn affected-system study ALWAYS scope by application_status or sheet_name — the queue is dominated by WITHDRAWN requests. ACTIVE is the live pipeline of REQUESTED (not built) capacity (the Interconnection Queue, Cluster Projects and Load Projects tabs, minus rows NYISO's own status code marks withdrawn); IN_SERVICE is built and energized; WITHDRAWN left the queue; AFFECTED_SYSTEM is out-of-NYISO projects studied for NY-system impact. A queue-MW total is requested capacity, never built — for built/operating capacity use query_power_capacity_v1.
study_status_code the distinct study-status codes observed in the served NYISO snapshot 5 1 = Scoping Meeting Pending, 6 = SRIS/SIS Approved, 11 = IA Completed, 14 = In Service Commercial, 0 = Withdrawn NYISO's serial study-phase legend (kept as-reported, may include alphanumeric codes like 3A / 5P / 15 / P): 0=Withdrawn, 1=Scoping Meeting, 2-3=Feasibility Study, 4-6=SRIS/SIS, 7-9=Facilities Study, 10-11=IA, 12=Under Construction, 13=In Service for Test, 14=In Service Commercial, 15=Partial In-Service. The FERC Order 2023 cluster tabs use a separate phase system. Filter by NYISO's EXACT value.
end_use the distinct end_use codes observed in the served NYISO snapshot (null before the 2026-07 edition and on non-load tabs) 8 DAT = DAT — as-reported (NYISO publishes no key for End-Use codes), DAT-AI = DAT-AI — as-reported, DAT-CM = DAT-CM — as-reported, M-CH = M-CH — as-reported, M-IN = M-IN — as-reported NYISO publishes NO key for these codes in the workbook — they are served verbatim and the labels below document the observed vocabulary only. The DAT family dominates the load queue (40 of 51 coded requests in the first edition that carries the column). Filter by NYISO's EXACT value; a load request NYISO left uncoded is null (as are all rows from pre-2026-07 snapshots — scope with as_of when counting).
zone the distinct NYISO load zones observed in the served snapshot 4 A = Zone A — West, F = Zone F — Capital, J = Zone J — New York City, K = Zone K — Long Island NYISO's eleven load zones, west to east: A=West, B=Genesee, C=Central, D=North, E=Mohawk Valley, F=Capital, G=Hudson Valley, H=Millwood, I=Dunwoodie, J=NYC, K=Long Island. A project spanning zones carries a multi-zone value as-reported. Filter by NYISO's EXACT value.
type_fuel the distinct type_fuel codes observed in the served NYISO snapshot 25 S = Solar, ES = Energy Storage (standalone battery), W = Wind (onshore), OSW = Off-Shore Wind, CR = CSR — Co-located Storage Resource: Energy Storage + Solar (hybrid) NYISO's resource type is a SHORT CODE — filter by NYISO's EXACT code, not a fuel word. The CSR codes are co-located storage HYBRIDS: CR = CSR (Energy Storage + Solar) and CW = CSR (Energy Storage + Wind) — NYISO's analog of a solar+storage / wind+storage hybrid (NOT a deliverability or capacity-service class). ES is standalone battery storage, OSW is offshore wind (distinct from onshore W), L is a load interconnection request (the Load Projects tab), and AC/DC are transmission (not generation, so they carry null MW). Values are AS-REPORTED, so a few older rows use a spelled-out or variant form (e.g. Solar for S, BAT for storage); a request with no type is null.

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

Checked Examples

Agent question Request params Checked output
How much requested MW and how many project-rows sit in the NYISO queue, by lifecycle status? {"group_by": ["application_status"]} nyiso-queue-by-status.json
Which NYISO load zones have the most active requested interconnection capacity? {"application_status": "ACTIVE", "group_by": ["zone"], "order_by": "sp_mw", "top_n": 11} active-summer-mw-by-zone.json
What load interconnection requests (the data-center-relevant tab) is NYISO studying, and how much peak load MW? {"group_by": ["state"], "sheet_name": "Load Projects"} load-projects.json
Return one NYISO queue project with a row-level citation. {"include_records": true, "limit": 1, "sheet_name": "Interconnection Queue"} 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_nyiso.
  2. Call describe_power_interconnection_queue_nyiso_v1 to inspect valid filters, groupings, metrics, and citation fields.
  3. Call query_power_interconnection_queue_nyiso_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 ↗