API reference · Quick run

Quick run

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.

Routes

POST/v2/run

Create a quick run

POST/v2/run

scope runasync · 202idempotency-keybatchable

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.

POST/v2/run
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" }
}'
import os
import requests

SCHEMA_API_KEY = os.environ["SCHEMA_API_KEY"]

r = requests.post(
    "https://api.schemalabs.ai/v2/run",
    headers={"Authorization": f"Bearer {SCHEMA_API_KEY}", "Idempotency-Key": "<unique key>"},
    json={
        "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", None, "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", None],
                ],
            },
        ],
        "target": {"mode": "auto"},
        "task": {"mode": "auto"},
    },
)
r.raise_for_status()
result = r.json()
const res = await fetch('https://api.schemalabs.ai/v2/run', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '<unique key>',
  },
  body: JSON.stringify({
    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" },
  }),
});
if (!res.ok) throw new Error(`Schema API error ${res.status}`);
const result = await res.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": {
    "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": {
    "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 }
    ]
  }
}
{
  "mode": "run",
  "run_id": "run_c81e0d",
  "status": "queued",
  "job_id": "job_c81e0d7f",
  "processing": "batch",
  "out": "warehouse://schema.outputs"
}

Headers

Idempotency-Keystring
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

tablesarray 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.
Item properties 3
- idstringrequired
  Your name for the table. Appears in every per-table output and in cross-table references such as crm_contacts.c1.
- columnsarray of stringsrequired
  Column names. They may be real names, opaque labels (c0, c1), or empty: Schema understands the values, not the names.
- rowsarray of arraysrequired
  Row values in column order. Use null for missing cells; missing cells are metered like any other cell.
dataarray 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.
basestringdefault latest
The Schema model to run on. Defaults to the latest (see GET /v2/models).
targetobjectdefault { "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.
Properties 2
- modestring
  auto (default) or none. Omit when supplying column.
  autonone
- columnstring
  A column name, qualified as table.column on multi-table input (for example cards_db.card_brand).
taskobjectdefault { "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.
Properties 2
- modestring
  Infer the task from the target.
  auto
- typestring
  Explicit task type. Set regression together with a numeric target.column; anomaly runs unsupervised and needs no target.
  classificationregressionanomaly
optionsobject
Per-request options.
Properties 3
- confidence_thresholdnumber
  Minimum confidence for cross-table column alignments and entity matches to be reported. Omit to use the service default.
- processingstringdefault realtime
  batch bills the job at the batch rate and runs with a completion window shown on the job’s eta.
  realtimebatch
- outstring
  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 13

modestring
Always "run".
run_idstring
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.
basestring
The base that produced the bundle.
feedstring
single_table or multi_table.
statusstring
complete, or queued / running on a 202.
summaryobject
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).
tablesarray of objects
One entry per input table.
Item properties 5
- idstring
  The table id you supplied.
- rowsinteger
  Row count.
- colsinteger
  Column count.
- sectorobject
  Vertical-agnostic sector identification from cell values alone, any domain, no metadata: top1 { name, confidence } and top5[], each with its own confidence.
- column_profilearray 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_mapobject | 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_rowsobject | 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.
imputationobject
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_selectionobject
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_selectionobject
mode, type, reason, overridable.
predictionobject | 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.