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/preflight
POST/v2/run

Preflight a call

POST/v2/preflight

scope run

Returns the exact cell count, the draw in the caller's bucket, the predicted wall time and any refusal a run, serve or generate call would meet, before any job starts. Runs no inference and bills nothing.

Send the body of the call you are about to make with op naming it: run, serve (with endpoint) or generate. The response counts cells per table and in total, applies the operation multiplier, and reports expected_seconds from the measured timing model.

draw follows the credential: a signed-in session sees the allowance bucket (percent used and cells remaining, never the allowance size); an API key sees the prepaid-credit cost in USD. refusal is null when the real call would go through, otherwise the same message the real call would return: per-run cap, inline run cap (a run without out above 1,000,000 cells), allowance shortfall, or no prepaid credits on a key.

POST/v2/preflight

curl -X POST 'https://api.schemalabs.ai/v2/preflight' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"

import os
import requests

SCHEMA_API_KEY = os.environ["SCHEMA_API_KEY"]

r = requests.post(
    "https://api.schemalabs.ai/v2/preflight",
    headers={"Authorization": f"Bearer {SCHEMA_API_KEY}"},
)
r.raise_for_status()
result = r.json()

const res = await fetch('https://api.schemalabs.ai/v2/preflight', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Schema API error ${res.status}`);
const result = await res.json();

{
  "cells": 12,
  "tables": [
    { "id": "inline", "cells": 12 }
  ],
  "op": "run",
  "multiplier": 1,
  "fresh_cell_equivalents": 12,
  "expected_seconds": 1,
  "draw": { "bucket": "prepaid_credits", "credit_usd": 0.000036, "sufficient": true },
  "refusal": null,
  "request_id": "req_1f3a"
}

Body application/json

opstringrequired
run, serve or generate.
endpointstring
For op: serve, the endpoint id or name.
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).
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.
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

200 with the counts; the call itself is never made.

Response fields 8

cellsinteger
Total cells the call would draw before the multiplier.
tablesarray
Per-table cell counts.
opstring
The operation checked.
multipliernumber
Operation multiplier (batch and synthetic draw at reduced rates).
fresh_cell_equivalentsinteger
Cells after the multiplier: what the meter records.
expected_secondsinteger
Predicted wall time for the real call. Clients that hold synchronous calls read this.
drawobject
bucket (allowance or prepaid_credits) with sufficient; percent_used and cells_remaining for the allowance, credit_usd for credits.
refusalstring
The refusal the real call would meet, or null.

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.

A run without out returns its bundle inline and is capped at 1,000,000 cells on every tier; above that, pass out to write the full bundle to a file or warehouse table, or create an endpoint. Both checks run at preflight.

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.