exascale.build
api ↗Connect

Docs → API reference

Robotics Adoption (share of plants using robots, workers exposed, robotics capex) API v1

Generated from core.contract.describe_robotics_adoption_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
edition product edition edition census_robotic_equipment_edition asm_2018_2021 (Annual Survey of Manufactures sample, annual 2018-2021) or ec_2022 (2022 Economic Census — reaches the small-plant universe the ASM sample does not). The editions are compared, never chained into one trend (PD-066). A coverage-universe label — the load-bearing scope dimension; cross-edition scopes carry an edition_scope note.
naics_vintage NAICS codebook vintage naics_vintage naics_vintage_pin Declared by each edition's own axis header (2017 NAICS in the ASM edition, 2022 NAICS in the EC edition) and served as-is — never recoded across vintages (PD-049). A codebook label, not a number.

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": [
      "avg_pct_plants_with_robots",
      "min_pct_plants_with_robots",
      "max_pct_plants_with_robots",
      "avg_pct_employees_exposed",
      "min_pct_employees_exposed",
      "max_pct_employees_exposed",
      "capex_thousand_usd",
      "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:

{
  "capex": [
    "capex_thousand_usd"
  ],
  "pct_employees_exposed": [
    "avg_pct_employees_exposed",
    "min_pct_employees_exposed",
    "max_pct_employees_exposed"
  ],
  "pct_plants_with_robots": [
    "avg_pct_plants_with_robots",
    "min_pct_plants_with_robots",
    "max_pct_plants_with_robots"
  ],
  "records": [
    "source_record_count"
  ]
}

Response summary fields:

Accepted fact policy:

Metric metadata:

Metric Category Unit Aggregation Additive Across Groups Authoritative Total Definition
avg_pct_plants_with_robots pct_plants_with_robots percent avg false summary.totals.avg_pct_plants_with_robots The share of manufacturing plants with industrial robots (a fraction of 1), exactly as the Census Industrial Robotic Equipment product publishes it, aggregated over the scope.
min_pct_plants_with_robots pct_plants_with_robots percent min false summary.totals.min_pct_plants_with_robots The share of manufacturing plants with industrial robots (a fraction of 1), exactly as the Census Industrial Robotic Equipment product publishes it, aggregated over the scope.
max_pct_plants_with_robots pct_plants_with_robots percent max false summary.totals.max_pct_plants_with_robots The share of manufacturing plants with industrial robots (a fraction of 1), exactly as the Census Industrial Robotic Equipment product publishes it, aggregated over the scope.
avg_pct_employees_exposed pct_employees_exposed percent avg false summary.totals.avg_pct_employees_exposed The share of manufacturing employees working at plants with industrial robots (a fraction of 1), exactly as published, aggregated over the scope.
min_pct_employees_exposed pct_employees_exposed percent min false summary.totals.min_pct_employees_exposed The share of manufacturing employees working at plants with industrial robots (a fraction of 1), exactly as published, aggregated over the scope.
max_pct_employees_exposed pct_employees_exposed percent max false summary.totals.max_pct_employees_exposed The share of manufacturing employees working at plants with industrial robots (a fraction of 1), exactly as published, aggregated over the scope.
capex_thousand_usd capex thousand USD sum false summary.totals.capex_thousand_usd Capital expenditures for industrial robotic equipment, in thousands of dollars, exactly as published, summed over the scope.
source_record_count records count count source records true summary.totals.source_record_count Count of normalized observations (edition × table × axis row × year) 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
edition every served observation carries exactly one edition 2 asm_2018_2021 = Annual Survey of Manufactures edition — annual 2018-2021, sample of larger plants; 2017 NAICS, ec_2022 = 2022 Economic Census edition — census-scope incl. small plants; 2022 NAICS; released 2025-08 The load-bearing scope dimension: the two editions measure DIFFERENT coverage universes and are compared, never chained into one trend (PD-066). A scope spanning both without grouping by edition carries an edition_scope note.
suppression any published cell can carry one 4 D = Withheld to avoid disclosing data of individual companies, S = Withheld because estimate did not meet publication standards, A = Not available / not applicable (file footnote), (s) = Estimate published; standard error exceeds 40% of the value (flag, not a withholding) A lettered cell is a null VALUE carrying its verbatim letter (PD-048 three-state — never a zero); an (s)-flagged estimate is published but its standard error exceeds 40% of the value (served with the flag, never silently).

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

Checked Examples

Agent question Request params Checked output
Which states have the highest share of manufacturing plants using robots (2022 census)? {"edition": "ec_2022", "group_by": ["state"], "order_by": "avg_pct_plants_with_robots", "table": "Percent of... Geo", "top_n": 10} most-automated-states.json
How does robot adoption differ by plant size? {"edition": "ec_2022", "group_by": ["plant_size"], "table": "Robot adoption and plant size"} adoption-by-plant-size.json
Show the national robot-adoption row with its full record and citation. {"data_year": 2022, "geo_area_name": "United States", "include_records": true, "limit": 1, "table": "Percent of... Geo"} adoption-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 robotics.adoption.
  2. Call describe_robotics_adoption_v1 to inspect valid filters, groupings, metrics, and citation fields.
  3. Call query_robotics_adoption_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 ↗