Batch decisions with the SDK

Batch decisions run a configured model across multiple examples. Create a job, retrieve it directly, cancel it, or poll until it reaches completed, failed, or cancelled.

Setup

Load the model and one stored example before starting a job:

from modaic import Modaic

modaic = Modaic()
model = modaic.models.get(workspace="acme", model="support-priority")
example_id = model.examples.list(page_size=1).items[0].id

Start and wait for a batch

Choose exactly one input mode: stored example IDs, inline examples, or every stored example.

Use model.jobs.batchDecisions (model.jobs.batch_decisions in Python) to create and list jobs for this model. Methods that take a job ID remain on modaic.batchDecisions / modaic.batch_decisions. With AsyncModaic, await each call.

job = model.jobs.batch_decisions.create(
    example_ids=[example_id],
    idempotency_key="support-backfill-2026-09-22",
)

finished = modaic.batch_decisions.wait(
    job.id,
    progress=True,
    poll_interval=1.0,
    timeout=300.0,
)

print(finished.status, finished.progress)

Set progress: true in TypeScript or progress=True in Python to show visual progress while waiting. Python uses tqdm in terminals and compatible notebooks, including with AsyncModaic. TypeScript updates a terminal bar on stderr or prints changed snapshots when output is redirected. In browsers without stderr, the TypeScript progress option has no effect. Output is silent by default.

The bar counts processed examples (completed plus failed), with failures shown separately. For example, the TypeScript display after a successful one-example batch:

Batch decisions 9e3d5d17 [====================] 1/1 examples | completed, 0 failed

Progress refreshes with each poll. A timeout stops waiting, not the job.

For inline inputs, use examples: [{ state: {...} }] in TypeScript or examples=[{"state": {...}}] in Python. Use scope: "all" or scope="all" to select every stored example.

List, retrieve, or cancel

recent = model.jobs.batch_decisions.list(limit=20)
current = modaic.batch_decisions.get(job.id)
modaic.batch_decisions.cancel(job.id)

Cancellation is idempotent and best-effort. Decisions completed before cancellation remain in each example's history.

See the Batch Decisions API reference for the complete wire contract.