---
title: Quick run · API reference
url: https://docs.schemalabs.ai/api-reference/run
description: Run Schema over the tables in one request: a stateless pass that returns the full output bundle, the same call the platform's Quick run page makes.
---

# Quick run

> Run Schema over the tables in one request: a stateless pass that returns the full output bundle, the same call the platform's Quick run page makes.

A quick run is the one stateless call in the product: one pass over the tables you send, returning the full output bundle in one response. Nothing is persisted, no dataset is registered, and the prediction is in-context, labeled `held_out: null`. The platform’s Quick run page is this same call.

Use a quick run for one-shot analysis, agents meeting a new source mid-task, and any call that wants the bundle and nothing kept. When you want a scored, servable layer that holds your pinned data and follows it over time, [create an endpoint](https://docs.schemalabs.ai/api-reference/endpoints#create-endpoint).

## Operations

### Create a quick run

`POST /v2/run` (scope: `run`)

Runs one stateless pass over any number of tables and returns the full bundle: sector, column profile, cross-table map (2+ tables), missing-value imputation, and an in-context prediction.

Send any number of tables from any number of sources: inline, or by dataset and connection id. Every output carries its own confidence. Two or more tables produce the cross-table map and unified rows; a single table returns `null` for both.

Large quick runs execute as async jobs: the response is `202` with a `job_id`, and the bundle is retrievable from the job when it completes, or written to `options.out`. Set `options.processing` to `"batch"` to bill at the batch rate; batch jobs run with a completion window shown on the job.

**Headers**

- `Idempotency-Key` (string): Optional. A unique key for this request. Retrying a POST with the same key and body never creates a duplicate job; the same key with a different body returns `409 conflict`.

**Body** (application/json)

- `tables` (array of objects): Any number of tables, inline. Two or more produce the cross-table map. Large data should be referenced by dataset or connection instead of sent inline (see `data`). Required unless `data` is supplied.
  - `id` (string, required): Your name for the table. Appears in every per-table output and in cross-table references such as `crm_contacts.c1`.
  - `columns` (array of strings, required): Column names. They may be real names, opaque labels (`c0`, `c1`), or empty: Schema understands the values, not the names.
  - `rows` (array of arrays, required): Row values in column order. Use `null` for missing cells; missing cells are metered like any other cell.
- `data` (array of strings): Dataset ids (`ds_...`) or connection refs (`snowflake://sales/live`, `s3://bucket/path`) to run on instead of, or in addition to, inline `tables`. Using a dataset or connection in a run registers nothing.
- `base` (string, default latest): The Schema model to run on. Defaults to the latest (see `GET /v2/models`).
- `target` (object, default { "mode": "auto" }): Which column to predict. `auto` lets Schema choose the most predictable eligible column and explains why; `column` names one; `none` returns an understanding-only bundle with no prediction slice.
  - `mode` (string): `auto` (default) or `none`. Omit when supplying `column`. One of: `auto`, `none`.
  - `column` (string): A column name, qualified as `table.column` on multi-table input (for example `cards_db.card_brand`).
- `task` (object, default { "mode": "auto" }): Prediction task type. `auto` infers it from the target (categorical → classification, numeric → regression). Anomaly detection runs on explicit request: set `type: "anomaly"`, which works without a target.
  - `mode` (string): Infer the task from the target. One of: `auto`.
  - `type` (string): Explicit task type. Set `regression` together with a numeric `target.column`; `anomaly` runs unsupervised and needs no target. One of: `classification`, `regression`, `anomaly`.
- `options` (object): Per-request options.
  - `confidence_threshold` (number): Minimum confidence for cross-table column alignments and entity matches to be reported. Omit to use the service default.
  - `processing` (string, default realtime): `batch` bills the job at the batch rate and runs with a completion window shown on the job’s eta. One of: `realtime`, `batch`.
  - `out` (string): For large runs: write the bundle to a file or warehouse table instead of returning it inline, for example `warehouse://schema.outputs`.

**Returns**

The output bundle, `200`; large quick runs and batch jobs return `202` with a job.

**Response fields**

- `mode` (string): Always `"run"`.
- `run_id` (string): Identifier of this quick run, for support and logs. The run’s job and run record appear in your org’s jobs and reports listings; submitted rows are discarded after the pass.
- `base` (string): The base that produced the bundle.
- `feed` (string): `single_table` or `multi_table`.
- `status` (string): `complete`, or `queued` / `running` on a `202`.
- `summary` (object): Headline counts: `tables`, `records_linked`, `records_total`, `keys_used` (`"none"`: no shared key was used to relate the tables), `shared_attributes`, and the `prediction` headline (`target`, `task`, `tier`, `held_out`).
- `tables` (array of objects): One entry per input table.
  - `id` (string): The table id you supplied.
  - `rows` (integer): Row count.
  - `cols` (integer): Column count.
  - `sector` (object): Vertical-agnostic sector identification from cell values alone, any domain, no metadata: `top1 { name, confidence }` and `top5[]`, each with its own confidence.
  - `column_profile` (array of objects): Per column: `name`, `role` (email, phone, date, name, code, measure, ...), `role_confidence`, `type` (categorical, numeric, datetime, text, boolean), `missing_pct`, `pii` (boolean).
- `cross_table_map` (object | null): Present on two or more tables. `summary`, `column_alignment[]` (each with `attribute`, `confidence`, and a format-invariance `example`), `entity_matches[]` (row pairs, `confidence`, `matched_on`), and `unified_schema` (`shared`, `a_only`, `b_only`). Every alignment and match carries its confidence and evidence.
- `unified_rows` (object | null): The cross-table map materialized into joined records: `schema`, `provenance`, `rows[]` (each with `entity`, `from`, `confidence`, `record`, and `shared_variants` showing each source’s raw value), `total`, and `sample_shown`. Paginated by cursor.
- `imputation` (object): Missing-value imputation: `filled[]` (table, row, column, value, method), `row_confidence[]` (table, row, confidence), and `total_filled`. Confidence is row-level, not per cell.
- `target_selection` (object): `mode` (`auto`, `user`, `none`), `column`, `reason`, `overridable`, and `candidates[]` (per column: `selected`, `eligible`, and a plain-language `reason`). `null` candidates when the target was user-specified.
- `task_selection` (object): `mode`, `type`, `reason`, `overridable`.
- `prediction` (object | null): The prediction slice, shaped by task type: classification (`label`, `confidence`, `probabilities`), regression (`value`, `median`, `std`, `quantiles`), anomaly (`anomaly_score`, `is_anomaly`, `threshold`). `tier` is `in_context`. `dropped_rows.missing_target` counts rows excluded because their target was missing. `null` when `target.mode` is `none`.

**Example request (cURL)**

```bash
curl -X POST 'https://api.schemalabs.ai/v2/run' \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Idempotency-Key: <unique key>" \
  -H "Content-Type: application/json" \
  -d '{
  "tables": [
    {
      "id": "crm_contacts",
      "columns": ["full_name", "phone", "email", "signup_date"],
      "rows": [
        ["Ana Kaya", "555-0142", "ana.k@example.com", "2024-11-03"],
        ["Devraj Nair", "555-0199", "d.nair@example.com", "2024-12-01"],
        ["Mira Ostrom", "555-0210", null, "2025-01-17"]
      ]
    },
    {
      "id": "cards_db",
      "columns": ["holder", "phone_e164", "card_brand", "credit_limit"],
      "rows": [
        ["KAYA, ANA", "+1 555 0142", "Visa", 12000],
        ["NAIR, DEVRAJ", "+1 555 0199", "Mastercard", 6500],
        ["OSTROM, MIRA", "+1 555 0210", "Amex", null]
      ]
    }
  ],
  "target": { "mode": "auto" },
  "task": { "mode": "auto" }
}'
```

**Example response (200)**

```json
{
  "mode": "run",
  "run_id": "run_9f2a4c",
  "base": "schema-2",
  "feed": "multi_table",
  "status": "complete",
  "summary": {
    "tables": 2,
    "records_linked": 3,
    "records_total": 3,
    "keys_used": "none",
    "shared_attributes": 2,
    "prediction": {
      "target": "cards_db.card_brand",
      "task": "classification",
      "tier": "in_context",
      "held_out": null
    }
  },
  "tables": [
    {
      "id": "crm_contacts",
      "rows": 3,
      "cols": 4,
      "sector": {
        "top1": {
          "name": "consumer financial services",
          "confidence": 0.89
        },
        "top5": [
          {
            "name": "consumer financial services",
            "confidence": 0.89
          },
          {
            "name": "customer relationship management",
            "confidence": 0.74
          },
          {
            "name": "credit card issuing",
            "confidence": 0.55
          },
          {
            "name": "marketing services",
            "confidence": 0.41
          },
          {
            "name": "retail banking",
            "confidence": 0.33
          }
        ]
      },
      "column_profile": [
        {
          "name": "full_name",
          "role": "name",
          "role_confidence": 0.93,
          "type": "categorical",
          "missing_pct": 0,
          "pii": true
        },
        {
          "name": "phone",
          "role": "phone",
          "role_confidence": 0.97,
          "type": "categorical",
          "missing_pct": 0,
          "pii": true
        },
        {
          "name": "email",
          "role": "email",
          "role_confidence": 0.98,
          "type": "categorical",
          "missing_pct": 0.33,
          "pii": true
        },
        {
          "name": "signup_date",
          "role": "date",
          "role_confidence": 0.95,
          "type": "datetime",
          "missing_pct": 0,
          "pii": false
        }
      ]
    },
    {
      "id": "cards_db",
      "rows": 3,
      "cols": 4,
      "sector": {
        "top1": {
          "name": "credit card issuing",
          "confidence": 0.91
        },
        "top5": [
          {
            "name": "credit card issuing",
            "confidence": 0.91
          },
          {
            "name": "consumer financial services",
            "confidence": 0.8
          },
          {
            "name": "retail banking",
            "confidence": 0.47
          },
          {
            "name": "payments processing",
            "confidence": 0.39
          },
          {
            "name": "consumer lending",
            "confidence": 0.31
          }
        ]
      },
      "column_profile": [
        {
          "name": "holder",
          "role": "name",
          "role_confidence": 0.91,
          "type": "categorical",
          "missing_pct": 0,
          "pii": true
        },
        {
          "name": "phone_e164",
          "role": "phone",
          "role_confidence": 0.98,
          "type": "categorical",
          "missing_pct": 0,
          "pii": true
        },
        {
          "name": "card_brand",
          "role": "category",
          "role_confidence": 0.94,
          "type": "categorical",
          "missing_pct": 0,
          "pii": false
        },
        {
          "name": "credit_limit",
          "role": "measure",
          "role_confidence": 0.96,
          "type": "numeric",
          "missing_pct": 0.33,
          "pii": false
        }
      ]
    }
  ],
  "cross_table_map": {
    "summary": {
      "tables": 2,
      "shared_attributes": 2,
      "entities_matched": 3,
      "columns_only_in_a": 2,
      "columns_only_in_b": 2,
      "keys_used": "none"
    },
    "column_alignment": [
      {
        "a": "crm_contacts.phone",
        "b": "cards_db.phone_e164",
        "attribute": "phone",
        "confidence": 0.96,
        "example": {
          "a": "555-0142",
          "b": "+1 555 0142"
        }
      },
      {
        "a": "crm_contacts.full_name",
        "b": "cards_db.holder",
        "attribute": "name",
        "confidence": 0.9,
        "example": {
          "a": "Ana Kaya",
          "b": "KAYA, ANA"
        }
      }
    ],
    "entity_matches": [
      {
        "a_row": 0,
        "b_row": 0,
        "confidence": 0.94,
        "matched_on": [
          "phone",
          "name"
        ]
      },
      {
        "a_row": 1,
        "b_row": 1,
        "confidence": 0.92,
        "matched_on": [
          "phone",
          "name"
        ]
      },
      {
        "a_row": 2,
        "b_row": 2,
        "confidence": 0.91,
        "matched_on": [
          "phone",
          "name"
        ]
      }
    ],
    "unified_schema": {
      "shared": [
        {
          "attribute": "phone",
          "from": [
            "crm_contacts.phone",
            "cards_db.phone_e164"
          ]
        },
        {
          "attribute": "name",
          "from": [
            "crm_contacts.full_name",
            "cards_db.holder"
          ]
        }
      ],
      "a_only": [
        "crm_contacts.email (email)",
        "crm_contacts.signup_date (date)"
      ],
      "b_only": [
        "cards_db.card_brand (category)",
        "cards_db.credit_limit (measure)"
      ]
    }
  },
  "unified_rows": {
    "schema": [
      "name",
      "phone",
      "email",
      "signup_date",
      "card_brand",
      "credit_limit"
    ],
    "rows": [
      {
        "entity": 0,
        "from": {
          "a_row": 0,
          "b_row": 0
        },
        "confidence": 0.94,
        "record": {
          "name": "Ana Kaya",
          "phone": "555-0142",
          "email": "ana.k@example.com",
          "signup_date": "2024-11-03",
          "card_brand": "Visa",
          "credit_limit": 12000
        },
        "shared_variants": {
          "phone": {
            "crm_contacts.phone": "555-0142",
            "cards_db.phone_e164": "+1 555 0142"
          }
        }
      }
    ],
    "total": 3,
    "sample_shown": 1
  },
  "imputation": {
    "filled": [
      {
        "table": "cards_db",
        "row": 2,
        "column": "credit_limit",
        "value": 8400,
        "method": "schema-2"
      }
    ],
    "row_confidence": [
      {
        "table": "cards_db",
        "row": 2,
        "confidence": 0.81
      }
    ],
    "total_filled": 1
  },
  "target_selection": {
    "mode": "auto",
    "column": "cards_db.card_brand",
    "reason": "most predictable target among the eligible categorical columns",
    "overridable": true,
    "candidates": [
      {
        "col": "cards_db.card_brand",
        "selected": true,
        "eligible": true,
        "reason": "most predictable from the other columns"
      },
      {
        "col": "cards_db.credit_limit",
        "eligible": false,
        "reason": "numeric measure, not a category"
      },
      {
        "col": "crm_contacts.email",
        "eligible": false,
        "reason": "looks like an identifier (mostly unique values)"
      }
    ]
  },
  "task_selection": {
    "mode": "auto",
    "type": "classification",
    "reason": "categorical target (card_brand)",
    "overridable": true
  },
  "prediction": {
    "target": "cards_db.card_brand",
    "task_type": "classification",
    "tier": "in_context",
    "classes": [
      "Amex",
      "Mastercard",
      "Visa"
    ],
    "dropped_rows": {
      "missing_target": 0
    },
    "results": [
      {
        "row": 0,
        "label": "Visa",
        "confidence": 0.94,
        "probabilities": {
          "Amex": 0.01,
          "Mastercard": 0.05,
          "Visa": 0.94
        }
      }
    ],
    "note": "in-context prediction; create an endpoint for a held-out score."
  }
}
```

**Prediction slice, regression (task.type "regression") (200)**

```json
{
  "prediction": {
    "target": "cards_db.credit_limit",
    "task_type": "regression",
    "tier": "in_context",
    "results": [
      {
        "row": 0,
        "value": 12480,
        "median": 12010,
        "std": 3120,
        "quantiles": {
          "0.1": 8400,
          "0.5": 12010,
          "0.9": 17900
        }
      }
    ]
  }
}
```

**Prediction slice, anomaly (task.type "anomaly") (200)**

```json
{
  "prediction": {
    "task_type": "anomaly",
    "tier": "in_context",
    "threshold": 0.9,
    "results": [
      {
        "row": 0,
        "anomaly_score": 0.97,
        "is_anomaly": true
      },
      {
        "row": 1,
        "anomaly_score": 0.12,
        "is_anomaly": false
      }
    ]
  }
}
```

**Large quick run, async (202)**

```json
{
  "mode": "run",
  "run_id": "run_c81e0d",
  "status": "queued",
  "job_id": "job_c81e0d7f",
  "processing": "batch",
  "out": "warehouse://schema.outputs"
}
```