---
title: Jobs · API reference
url: https://docs.schemalabs.ai/api-reference/jobs
description: List, poll, and cancel the async jobs behind endpoint creation, refresh, upgrade, synthetic data generation, and batch quick runs.
---

# Jobs

> List, poll, and cancel the async jobs behind endpoint creation, refresh, upgrade, synthetic data generation, and batch quick runs.

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.

## The job object

**Attributes**

- `job_id` (string): `job_...`, immutable.
- `kind` (string): What the job does. `batch` is a run or generation submitted with `processing: "batch"`. One of: `run`, `create`, `refresh`, `upgrade`, `generate`, `batch`.
- `status` (string): Lifecycle. Poll until terminal (`done`, `failed`, `cancelled`, `expired`). One of: `queued`, `running`, `done`, `failed`, `cancelled`, `expired`.
- `progress` (integer): 0 to 100.
- `phase` (string | null): Current phase label while running.
- `label` (string): Human label: the endpoint name, run report id, or job description.
- `endpoint_id` (string): The endpoint the job acts on; empty for stateless runs.
- `report_id` (string): The report the job minted, once complete.
- `eta` (object | null): `basis`, `due_at`, `seconds_remaining`. `null` once the job runs.
- `error` (string): On failure: the error message. Empty otherwise.
- `logs` (array of strings): Recent operational log lines (retrieve only).
- `created_at` (string): Submit time.
- `updated_at` (string): Last state change.

```json
{
  "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"
}
```

## Operations

### List jobs

`GET /v2/jobs` (scope: `read`)

Lists in-flight and recent jobs.

**Query parameters**

- `status` (string): Filter by status.
- `limit` (integer, default 20): Page size.
- `cursor` (string): Cursor from a previous page.

**Returns**

A page of job objects.

**Example request (cURL)**

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

**Example response (200)**

```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
}
```

### Retrieve a job

`GET /v2/jobs/:id` (scope: `read`)

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

**Path parameters**

- `id` (string, required): `job_...`.

**Returns**

The [job object](#the-job-object).

**Example request (cURL)**

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

**Example response (200)**

```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}"
  ]
}
```

> 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.

**Path parameters**

- `id` (string, required): `job_...`.

**Returns**

The job object with `status: "cancelled"`.

**Example request (cURL)**

```bash
curl -X POST 'https://api.schemalabs.ai/v2/jobs/job_b3d1f0e2/cancel' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"
```

**Example response (200)**

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

> 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.