exascale.build
api ↗Connect

Docs → API reference

Power Interconnection Queue (PJM cluster/cycle) API v1

Generated from core.contract.describe_power_interconnection_queue_pjm_cycle_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": [
      "requested_max_output_mw",
      "requested_summer_mw",
      "requested_winter_mw",
      "in_service_mw",
      "ltf_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:

{
  "built_mw": [
    "in_service_mw"
  ],
  "records": [
    "source_record_count"
  ],
  "requested_mw": [
    "requested_max_output_mw",
    "requested_summer_mw",
    "requested_winter_mw"
  ],
  "transmission_mw": [
    "ltf_mw"
  ]
}

Response summary fields:

Accepted fact policy:

Metric metadata:

Metric Category Unit Aggregation Additive Across Groups Authoritative Total Definition
requested_max_output_mw requested_mw MW sum true summary.totals.requested_max_output_mw The project's Maximum Facility Output (MFO) — the headline requested size.
requested_summer_mw requested_mw MW sum true summary.totals.requested_summer_mw The project's requested Capacity interconnection (summer net) MW.
requested_winter_mw requested_mw MW sum true summary.totals.requested_winter_mw The project's requested net winter MW (a winter MW figure, not MWh).
in_service_mw built_mw MW sum true summary.totals.in_service_mw The realized BUILT MW once the project is in service (not a request).
ltf_mw transmission_mw MW sum true summary.totals.ltf_mw The long-term firm transmission MW for transmission requests in the cycle grid.
source_record_count records count count source records true summary.totals.source_record_count Count of cluster-cycle projects in the current result scope (one atom = one PJM project).

Rollup rules:

Detail record fields returned when include_records is true:

Row-level citation fields:

Aggregate citation fields:

Codebooks

Field Coverage Codes Examples Note
cycle the distinct cycle values observed in the served snapshot 3 TC1 = Transition Cycle 1 (legacy backlog over the network-upgrade threshold), TC2 = Transition Cycle 2 (remaining legacy backlog), C01 = Cycle 1 — the first reopened steady-state cluster cycle TC1/TC2 are the transition cycles re-processing the pre-Order-2023 serial backlog; C01+ are the reopened STEADY-STATE cycles (the new intake). Filter cycle=C01 for the newest reopened-queue projects. Each cycle is studied as a cluster, not first-come serial.
status the distinct status values observed in the served snapshot 5 Active = Active — a live request still in the cluster, Withdrawn = Withdrawn — left the queue (the grid is withdrawn-dominated), EP = Engineering & Procurement, UC = Under Construction, UC-ISP = Under Construction — In-Service Pending ALWAYS scope by status — the grid is withdrawn-dominated. Active is the live pipeline; EP = engineering & procurement; UC/UC-ISP = under construction; Withdrawn left the queue. Requested MW is never built — for built MW use the in_service_mw field or query_power_capacity_v1.
fuel the distinct fuel values observed in the served snapshot 6 Solar = Solar, Storage = Storage, Natural Gas = Natural gas, Wind = Wind, Offshore Wind = Offshore wind Filter fuel by PJM's EXACT value (e.g. Natural Gas, Solar, Storage). Multi-tech projects are COMMA-joined with PJM's own Hybrid tag, e.g. Solar,Storage,Hybrid (flagged is_hybrid) — note this differs from the New Services queue feed's ';'-join.

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

Checked Examples

Agent question Request params Checked output
How many projects are in each PJM cluster cycle (TC1/TC2 transition vs the reopened C01)? {"group_by": ["cycle"]} pjm-cycle-by-cycle.json
Which states have the most requested interconnection capacity in PJM's cluster cycles? {"group_by": ["state"], "order_by": "requested_max_output_mw", "top_n": 10} requested-mw-by-state.json
What fuels are the active PJM cluster-cycle requests, and how much capacity? {"group_by": ["fuel"], "status": "Active"} active-requests-by-fuel.json
Return one PJM reopened-cycle (C01) project with a row-level citation. {"cycle": "C01", "include_records": true, "limit": 1} cycle-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_pjm_cycle.
  2. Call describe_power_interconnection_queue_pjm_cycle_v1 to inspect valid filters, groupings, metrics, and citation fields.
  3. Call query_power_interconnection_queue_pjm_cycle_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 ↗