exascale.build
api ↗Connect

Docs → API reference

AI Infrastructure Employment (data centers + semiconductors) API v1

Generated from core.contract.describe_ai_infrastructure_employment_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
avg_wkly_wage average weekly wage avg_wkly_wage bls_qcew_average_weekly_wage BLS's published average weekly wage ($) for the cell (total quarterly wages ÷ average monthly employment ÷ 13 weeks, computed by BLS), served on DETAIL records only. A per-cell average — non-additive: never sum or average it across cells; a withheld (disclosure 'N'/'-') cell carries no value.

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": [
      "qtrly_estabs",
      "month1_emplvl",
      "month2_emplvl",
      "month3_emplvl",
      "total_qtrly_wages",
      "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:

{
  "employment": [
    "month1_emplvl",
    "month2_emplvl",
    "month3_emplvl"
  ],
  "establishments": [
    "qtrly_estabs"
  ],
  "records": [
    "source_record_count"
  ],
  "wages": [
    "total_qtrly_wages"
  ]
}

Response summary fields:

Accepted fact policy:

Metric metadata:

Metric Category Unit Aggregation Additive Across Groups Authoritative Total Definition
qtrly_estabs establishments count sum true summary.totals.qtrly_estabs Count of establishments (physical locations) covered by unemployment insurance in the industry × area × ownership in scope, for the quarter, exactly as BLS publishes it in QCEW.
month1_emplvl employment count sum true summary.totals.month1_emplvl BLS QCEW covered employment in the first month of the quarter for the industry × area × ownership in scope, served verbatim — INDUSTRY employment, not an 'AI jobs' count.
month2_emplvl employment count sum true summary.totals.month2_emplvl BLS QCEW covered employment in the second month of the quarter for the industry × area × ownership in scope, served verbatim — INDUSTRY employment, not an 'AI jobs' count.
month3_emplvl employment count sum true summary.totals.month3_emplvl BLS QCEW covered employment in the third month of the quarter for the industry × area × ownership in scope, served verbatim — INDUSTRY employment, not an 'AI jobs' count.
total_qtrly_wages wages USD sum true summary.totals.total_qtrly_wages Sum of total quarterly wages ($) paid by UI-covered employers in the industry × area × ownership in scope, exactly as BLS publishes it in QCEW.
source_record_count records count count source records true summary.totals.source_record_count Count of normalized source records (area × ownership × industry × quarter cells) 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
industry the eight pinned industry series: the two AI-infrastructure NAICS + the PD-069 place-based local-economy set 8 518210 = Computing infrastructure providers, data processing, web hosting, and related services, 334413 = Semiconductor and related device manufacturing, 10 = Total, all industries, 23 = Construction, 236220 = Commercial and institutional building construction DISTINCT series, never conflated. The only ancestries: '10' (total, all industries) contains every other series, and 23 (construction) contains 236220 (commercial building). The remaining series are mutually DISJOINT — 721/722 sit under NAICS 72 (not served), NOT under retail '44-45'. Each code lives at its own agglvl depth ('10' at x0/x1; 23 and '44-45' at x4; 721/722 at x5; 236220/518210/334413 at x8); never sum a series with its ancestor. NAICS vintage: 2014-2021 coded under NAICS 2017, 2022Q1-forward under NAICS 2022 (BLS never recodes history) — the 2022 revision REDEFINED 518210, so its cross-2022Q1 level shift is reclassification, not a real change.
ownership the ownership sectors QCEW publishes 8 0 = Total Covered, 1 = Federal Government, 2 = State Government, 3 = Local Government, 4 = International Government own_code 5 = Private (the usual filter). 0 'Total Covered' and 8 'Total Government' are TOTALS that already contain their components — never sum a total with its parts.
agglvl national / state / county at each pinned industry depth (MSA excluded — CBSA codes don't fit the county_fips anchor) 15 10 = National, total covered (all ownerships), 11 = National, total — by ownership, 14 = National, by NAICS sector, 15 = National, by NAICS 3-digit, 18 = National, by 6-digit NAICS First digit = geography (1 national / 5 state / 7 county); second digit = industry depth (0 total covered, 1 total by ownership, 4 NAICS sector, 5 NAICS 3-digit, 8 NAICS 6-digit). Geography NESTS — 18 national contains 58 state contains 78 county — and the total depth (x0/x1, industry '10') contains every other depth. Filter to one level (or group_by agglvl) to avoid double-counting. Depth follows the industry_code: '10' lives at x0/x1, 23 and '44-45' at x4, 721/722 at x5, 236220/518210/334413 at x8.

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

Checked Examples

Agent question Request params Checked output
How many people work in the U.S. data-center industry (NAICS 518210, private), by quarter? {"agglvl": "18", "group_by": ["quarter"], "industry_code": "518210", "own_code": "5"} datacenter-employment-national.json
Which Virginia counties have the most data-center-industry employment in 2025 Q4? {"agglvl": "78", "group_by": ["county_fips"], "industry_code": "518210", "order_by": "month3_emplvl", "own_code": "5", "quarter": "2025-10-01", "state": "VA", "top_n": 10} datacenter-employment-va-counties.json
How does U.S. data-center-industry employment compare to semiconductor manufacturing in 2025 Q4 (private)? {"agglvl": "18", "group_by": ["industry_code"], "own_code": "5", "quarter": "2025-10-01"} datacenter-vs-semiconductor-national.json
Return one national data-center-industry employment record with a row-level citation. {"agglvl": "18", "include_records": true, "industry_code": "518210", "limit": 1, "own_code": "5", "quarter": "2025-10-01"} datacenter-employment-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 ai_infrastructure.employment.
  2. Call describe_ai_infrastructure_employment_v1 to inspect valid filters, groupings, metrics, and citation fields.
  3. Call query_ai_infrastructure_employment_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 ↗