API reference · Jobs

Jobs

Endpoint creation, refresh, upgrade, synthetic generation, and large or batch runs are async so clients and CI never block. Each returns 202 with a job_id. Poll the job for status; job completion also raises a platform notification and an email.

A job either completes with its full result or fails as job_failed. Failed jobs bill nothing. A batch job that misses its completion window expires unbilled and can be resubmitted.

Routes

objectThe job object
GET/v2/jobs
GET/v2/jobs/:id
POST/v2/jobs/:id/cancel

The job object

The job objectjson

{
  "job_id": "job_9a5b01d4",
  "kind": "create",
  "status": "running",
  "progress": 60,
  "phase": "held-out evaluation",
  "label": "churn",
  "endpoint_id": "{endpoint_id}",
  "report_id": "",
  "eta": null,
  "error": "",
  "logs": [],
  "created_at": "2026-03-10T14:07:02Z",
  "updated_at": "2026-03-10T14:08:41Z"
}

Attributes

job_idstring
job_..., immutable.
kindstring
What the job does. batch is a run or generation submitted with processing: "batch".
runcreaterefreshupgradegeneratebatch
statusstring
Lifecycle. Poll until terminal (done, failed, cancelled, expired).
queuedrunningdonefailedcancelledexpired
progressinteger
0 to 100.
phasestring | null
Current phase label while running.
labelstring
Human label: the endpoint name, run report id, or job description.
endpoint_idstring
The endpoint the job acts on; empty for stateless runs.
report_idstring
The report the job minted, once complete.
etaobject | null
basis, due_at, seconds_remaining. null once the job runs.
errorstring
On failure: the error message. Empty otherwise.
logsarray of strings
Recent operational log lines (retrieve only).
created_atstring
Submit time.
updated_atstring
Last state change.

List jobs

GET/v2/jobs

scope read

Lists in-flight and recent jobs.

GET/v2/jobs

curl 'https://api.schemalabs.ai/v2/jobs?status=queued' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"

import os
import requests

SCHEMA_API_KEY = os.environ["SCHEMA_API_KEY"]

r = requests.get(
    "https://api.schemalabs.ai/v2/jobs?status=queued",
    headers={"Authorization": f"Bearer {SCHEMA_API_KEY}"},
)
r.raise_for_status()
result = r.json()

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

{
  "jobs": [
    {
      "job_id": "job_4c1f88a2",
      "kind": "batch",
      "status": "queued",
      "progress": 0,
      "phase": "",
      "label": "stateless run",
      "endpoint_id": "",
      "report_id": "",
      "eta": {
        "basis": "queued",
        "due_at": "2026-08-15T14:07:02Z",
        "seconds_remaining": null
      },
      "error": "",
      "created_at": "2026-08-14T14:07:02Z",
      "updated_at": "2026-08-14T14:07:02Z"
    }
  ],
  "next_cursor": null,
  "total": 1
}

Query parameters

statusstring
Filter by status.
limitintegerdefault 20
Page size.
cursorstring
Cursor from a previous page.

Returns

A page of job objects.

Retrieve a job

GET/v2/jobs/:id

scope read

Returns a job’s status, progress, ETA, and logs. Poll this until status is terminal.

GET/v2/jobs/:id

curl 'https://api.schemalabs.ai/v2/jobs/job_9a5b01d4' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"

import os
import requests

SCHEMA_API_KEY = os.environ["SCHEMA_API_KEY"]

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

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

{
  "job_id": "job_9a5b01d4",
  "kind": "create",
  "status": "done",
  "progress": 100,
  "phase": null,
  "label": "churn",
  "endpoint_id": "{endpoint_id}",
  "report_id": "r_8f3a",
  "eta": null,
  "error": "",
  "logs": [
    "14:07:02 pinned ds_crm01 @ dsv_2b81, ds_bill01 @ dsv_c4e7",
    "14:08:41 held-out: in-context split, seed 42, 17675/4419",
    "14:09:31 live at /v2/serve/{endpoint_id}"
  ]
}

Path parameters

idstringrequired
job_....

Returns

The job object.

Poll with backoff (for example 2s, 4s, 8s, then every 15s). Creation typically completes in minutes; batch jobs run within a completion window, shown on the job’s eta.

Cancel a job

POST/v2/jobs/:id/cancel

scope manage

Stops a queued or running job. Cancelled jobs bill nothing.

POST/v2/jobs/:id/cancel

curl -X POST 'https://api.schemalabs.ai/v2/jobs/job_b3d1f0e2/cancel' \
  -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/jobs/job_b3d1f0e2/cancel",
    headers={"Authorization": f"Bearer {SCHEMA_API_KEY}"},
)
r.raise_for_status()
result = r.json()

const res = await fetch('https://api.schemalabs.ai/v2/jobs/job_b3d1f0e2/cancel', {
  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();

{
  "job_id": "job_b3d1f0e2",
  "kind": "batch",
  "status": "cancelled",
  "updated_at": "2026-08-14T14:08:10Z"
}

Path parameters

idstringrequired
job_....

Returns

The job object with status: "cancelled".

Cancelling an endpoint creation stops the creation; delete the endpoint or create it again. Cancelling a refresh or upgrade leaves the endpoint serving its previous state.