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:

import { Modaic } from "modaic";

const modaic = new Modaic();
const model = await modaic.models.get("acme", "support-priority");
const examples = await model.examples.list({ pageSize: 1 });
const exampleId = examples.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.

const job = await model.jobs.batchDecisions.create({
  exampleIds: [exampleId],
  idempotencyKey: "support-backfill-2026-09-22",
});

const finished = await modaic.batchDecisions.wait(job.id, {
  progress: true,
  pollIntervalMs: 1_000,
  timeoutMs: 300_000,
});

console.log(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

const recent = await model.jobs.batchDecisions.list({ limit: 20 });
const current = await modaic.batchDecisions.get(job.id);
await modaic.batchDecisions.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.