---
title: "Start Batch Predictions Job"
method: POST
path: "/api/v1/jobs/batch/predictions"
---

# Start Batch Predictions Job

`POST /api/v1/jobs/batch/predictions`

Start an async batch prediction job.

Two input modes (mutually exclusive):

* ``examples`` — ingest brand-new examples and run predictions on them.
* ``example_ids`` — re-predict existing examples (referenced by their
  ClickHouse ids). Predictions are inserted as new versions on the
  existing example rows; no new examples rows are written.

When ``compute_confidence=True`` the worker pre-warms a probe scorer
container per arbiter and, after predictions persist, kicks off Modal
batch confidence scoring filtered to the prediction_ids produced by
this job (so we don't accidentally re-score unrelated NULL-confidence
rows). Predictions are visible to clients during the scoring phase via
``GET /results`` — confidence populates as Modal streams.

Phases visible via ``GET /{job_id}`` and SSE: ``predicting → scoring →
done`` (or ``failed``).

## Headers

- `authorization` string, nullable

## Cookies

- `modaic_session` string, nullable

## Request body

- BatchPredictionsJobRequest — Request body for ``POST /api/v1/jobs/batch/predictions``. Either ``examples`` or ``example_ids`` must be set, not both. The ``example_ids`` path re-predicts existing examples (by their ClickHouse ids) instead of ingesting brand-new ones; predictions are inserted as new versions on the existing example rows.
  - `arbiters` BatchArbiter[], required
    - `arbiter_repo` string, required
    - `arbiter_revision` string
  - `examples` BatchExample[], nullable
    - `input` object, required
    - `alt_id` string, nullable
    - `ground_truth` object, nullable
    - `ground_reasoning` string
    - `split` 'train' | 'test' | 'none', nullable
  - `example_ids` string[], nullable
  - `compute_confidence` boolean

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/modaic-ai/apis/modaic-api.md) · [All operations](https://skmtc.net/modaic-ai/apis/modaic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/modaic-ai/modaic-api/revisions/43a90513ac59/schema)