Run a batch

Batches require account access and an enabled unified v2 batch API. Both SDKs support the complete lifecycle.

const batch = await agent.batch([
  'Research acme.example',
  'Research beta.example',
], {
  name: 'Company checks',
  maxConcurrent: 2,
  idempotencyKey: 'company-checks-001',
});
const status = await agent.waitBatch(batch.id);
const results = await agent.getBatchResults(batch.id);
console.log(status, results);

Batches accept 1–100 nonblank inputs of up to 8,000 characters each. The SDK rejects oversized batches rather than splitting or retrying them.

const batch = await agent.batch({
  csv: 'input,segment\nResearch acme.example,enterprise',
  inputColumn: 'input',
}, { name: 'CSV checks' });

CSV can be a string or uploaded File/Blob and is limited to 1 MB. Headers must be unique. Extra columns are retained as row data.

waitBatch can return on partial failure, failure, cancellation, or a pause that requires attention. Check row outcomes and read each row's run_id for its report. cancelBatch stops new dispatches; running rows settle independently. Explicit retryBatch calls can consume more credits.

batch = agent.batch(
    ["Research acme.example", "Research beta.example"],
    name="Company checks", max_concurrent=2,
    form_inputs=[{"Company": "Acme"}, {"Company": "Beta"}],
    idempotency_key="company-checks-001",
)
status = agent.wait_batch(batch["id"])
results = agent.get_batch_results(batch["id"], row_status="completed")
csv_batch = agent.batch({
    "csv": "input,segment\nResearch acme.example,enterprise",
    "input_column": "input",
})

Python CSV input is text; TypeScript also accepts Blob/File. formInputs in TypeScript and form_inputs in Python align with the questions, one dictionary or null per question. Batch options include effort, output schema, response language, concurrency (1–20), and a credit limit. Use maxCredits / max_credits to bound each batch.

Use listBatches/list_batches with cursor, limit, and optional status. getBatch/get_batch accepts includeRows/include_rows. getBatchResults/get_batch_results filters rowStatus/row_status by queued, running, completed, or failed. retryBatch/retry_batch accepts rowNumber/row_number for an explicit row retry. cancelBatch/cancel_batch stops pending dispatches. Inspect partial failures and paused_reason before deciding to retry.