Batch API

Overview

The Batch API allows you to submit multiple simulations in a single request. Batches execute simulations in parallel with automatic progress tracking and cost management.

Batch Features

Parallel Execution: Run multiple simulations simultaneously
Progress Tracking: Monitor individual job and overall batch progress
Cost Management: Set budget caps and track actual costs
Fail-Fast Mode: Stop on first failure or continue
Priority Control: Set batch priority (0-100)

Create Batch

Submit a batch of simulations to run. Returns immediately with batch ID.

POST /simulations/batch

curl -X POST http://localhost:8080/simulations/batch \
  -H "X-API-Key: tp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "simulations": [
      {
        "template_id": "board_meeting",
        "entity_count": 5,
        "timepoint_count": 10
      },
      {
        "template_id": "crisis_response",
        "entity_count": 4,
        "timepoint_count": 8
      }
    ],
    "parallel_jobs": 2,
    "fail_fast": false,
    "budget_cap_usd": 1.00,
    "priority": 50
  }'

Request Body

simulations

array

required

Array of simulation requests (same format as POST /simulations)

parallel_jobs

integer

default:"3"

Number of simulations to run in parallel

fail_fast

boolean

default:"false"

Stop batch on first failure

budget_cap_usd

number

Maximum cost for batch (USD)

priority

integer

default:"50"

Batch priority (0-100, higher = more important)

metadata

object

Custom metadata

Response

Status: 202 Accepted

batch_id

string

Unique batch identifier

status

string

Batch status: PENDING, RUNNING, PARTIAL, COMPLETED, FAILED, or CANCELLED

created_at

string

Creation timestamp

priority

integer

Batch priority

fail_fast

boolean

Fail-fast mode enabled

parallel_jobs

integer

Parallel job limit

progress

object

Progress tracking

progress.total_jobs

integer

Total jobs in batch

progress.pending_jobs

integer

Jobs pending

progress.running_jobs

integer

Jobs running

progress.completed_jobs

integer

Jobs completed

progress.failed_jobs

integer

Jobs failed

progress.cancelled_jobs

integer

Jobs cancelled

progress.progress_percent

integer

Overall progress percentage

cost

object

Cost tracking

cost.estimated_cost_usd

number

Estimated cost

cost.actual_cost_usd

number

Actual cost so far

cost.budget_cap_usd

number

Budget cap (if set)

cost.budget_remaining_usd

number

Remaining budget

cost.tokens_used

integer

Tokens used

job_ids

array

Array of created job IDs

{
  "batch_id": "batch-abc123def456",
  "status": "PENDING",
  "created_at": "2026-03-06T12:00:00Z",
  "started_at": null,
  "completed_at": null,
  "priority": 50,
  "fail_fast": false,
  "parallel_jobs": 2,
  "progress": {
    "total_jobs": 2,
    "pending_jobs": 2,
    "running_jobs": 0,
    "completed_jobs": 0,
    "failed_jobs": 0,
    "cancelled_jobs": 0,
    "progress_percent": 0
  },
  "cost": {
    "estimated_cost_usd": 0.10,
    "actual_cost_usd": 0.0,
    "budget_cap_usd": 1.00,
    "budget_remaining_usd": 1.00,
    "tokens_used": 0
  },
  "job_ids": ["job-001", "job-002"],
  "error_message": null,
  "owner_id": "user-123",
  "metadata": null
}

Batch Size Limits

Tier	Max Batch Size
Free	5
Basic	20
Pro	50
Enterprise	100

Get Batch Status

Get details about a specific batch.

GET /simulations/batch/{batch_id}

curl -X GET http://localhost:8080/simulations/batch/batch-abc123def456 \
  -H "X-API-Key: tp_your_api_key_here"

Response

Returns batch object with updated progress and status.

Errors

404 Not Found - Batch doesn’t exist
403 Forbidden - Not the batch owner

Get Batch with Jobs

Get batch details including all individual job details.

GET /simulations/batch/{batch_id}/jobs

curl -X GET http://localhost:8080/simulations/batch/batch-abc123def456/jobs \
  -H "X-API-Key: tp_your_api_key_here"

Response

batch

object

Batch metadata

jobs

array

Array of job objects with full details

{
  "batch": {
    "batch_id": "batch-abc123def456",
    "status": "RUNNING",
    "progress": {
      "total_jobs": 2,
      "completed_jobs": 1,
      "running_jobs": 1,
      "progress_percent": 50
    }
  },
  "jobs": [
    {
      "job_id": "job-001",
      "status": "COMPLETED",
      "template_id": "board_meeting",
      "cost_usd": 0.05,
      "completed_at": "2026-03-06T12:05:00Z"
    },
    {
      "job_id": "job-002",
      "status": "RUNNING",
      "template_id": "crisis_response",
      "progress_percent": 60
    }
  ]
}

List Batches

List your batch jobs with optional filtering.

GET /simulations/batch

curl -X GET "http://localhost:8080/simulations/batch?status=RUNNING&page=1" \
  -H "X-API-Key: tp_your_api_key_here"

Query Parameters

status

string

Filter by status

page

integer

default:"1"

Page number

page_size

integer

default:"20"

Batches per page (1-100)

Response

batches

array

Array of batch objects

total

integer

Total batch count

page

integer

Current page

page_size

integer

Page size

Cancel Batch

Cancel a running or pending batch.

POST /simulations/batch/{batch_id}/cancel

curl -X POST http://localhost:8080/simulations/batch/batch-abc123def456/cancel \
  -H "X-API-Key: tp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "No longer needed",
    "cancel_running": true
  }'

Request Body

reason

string

Cancellation reason (optional)

cancel_running

boolean

default:"true"

Whether to cancel currently running jobs

Response

Returns batch object with status CANCELLED.

Get Batch Statistics

Get statistics about your batches.

GET /simulations/batch/stats

curl -X GET http://localhost:8080/simulations/batch/stats \
  -H "X-API-Key: tp_your_api_key_here"

Response

total_batches

integer

Total batches created

pending

integer

Batches pending

running

integer

Batches running

completed

integer

Batches completed

failed

integer

Batches failed

cancelled

integer

Batches cancelled

total_jobs

integer

Total jobs across all batches

total_cost_usd

number

Total cost

total_tokens

integer

Total tokens used

Get Usage Status

Get current usage and quota status.

GET /simulations/batch/usage

curl -X GET http://localhost:8080/simulations/batch/usage \
  -H "X-API-Key: tp_your_api_key_here"

Response

user_id

string

Your user ID

tier

string

Your subscription tier

period

string

Current billing period (YYYY-MM)

days_remaining

integer

Days remaining in period

api_calls_used

integer

API calls used this month

simulations_used

integer

Simulations run this month

cost_used_usd

number

Cost accumulated this month

tokens_used

integer

Tokens used this month

api_calls_limit

integer

API calls limit (-1 = unlimited)

simulations_limit

integer

Simulations limit (-1 = unlimited)

cost_limit_usd

number

Cost limit (-1 = unlimited)

max_batch_size

integer

Maximum batch size

api_calls_remaining

integer

Remaining API calls

simulations_remaining

integer

Remaining simulations

cost_remaining_usd

number

Remaining budget

is_quota_exceeded

boolean

Whether any quota is exceeded

quota_exceeded_reason

string

Reason for quota exceeded (if applicable)

{
  "user_id": "user-123",
  "tier": "pro",
  "period": "2026-03",
  "days_remaining": 25,
  "api_calls_used": 5432,
  "simulations_used": 127,
  "cost_used_usd": 6.35,
  "tokens_used": 158750,
  "api_calls_limit": 100000,
  "simulations_limit": 1000,
  "cost_limit_usd": 100.00,
  "max_batch_size": 50,
  "api_calls_remaining": 94568,
  "simulations_remaining": 873,
  "cost_remaining_usd": 93.65,
  "is_quota_exceeded": false,
  "quota_exceeded_reason": null
}

Get Usage History

Get usage history for past billing periods.

GET /simulations/batch/usage/history

curl -X GET "http://localhost:8080/simulations/batch/usage/history?periods=6" \
  -H "X-API-Key: tp_your_api_key_here"

Query Parameters

periods

integer

default:"6"

Number of past periods to retrieve

Response

current

object

Current period usage (same as /usage)

history

array

Array of historical period usage

{
  "current": {
    "period": "2026-03",
    "api_calls_used": 5432,
    "simulations_used": 127,
    "cost_used_usd": 6.35
  },
  "history": [
    {
      "period": "2026-02",
      "api_calls": 8521,
      "simulations_run": 203,
      "simulations_completed": 198,
      "simulations_failed": 5,
      "cost_usd": 10.15,
      "tokens_used": 253750
    },
    {
      "period": "2026-01",
      "api_calls": 7834,
      "simulations_run": 187,
      "simulations_completed": 183,
      "simulations_failed": 4,
      "cost_usd": 9.35,
      "tokens_used": 233750
    }
  ]
}

CLI Commands

REST API

Python API

Export Formats

Overview

Batch Features

Create Batch

Request Body

Response

Batch Size Limits

Get Batch Status

Response

Errors

Get Batch with Jobs

Response

List Batches

Query Parameters

Response

Cancel Batch

Request Body

Response

Get Batch Statistics

Response

Get Usage Status

Response

Get Usage History

Query Parameters

Response

Build docs developers (and LLMs) love

CLI Commands

REST API

Python API

Export Formats

​Overview

​Batch Features

​Create Batch

​Request Body

​Response

​Batch Size Limits

​Get Batch Status

​Response

​Errors

​Get Batch with Jobs

​Response

​List Batches

​Query Parameters

​Response

​Cancel Batch

​Request Body

​Response

​Get Batch Statistics

​Response

​Get Usage Status

​Response

​Get Usage History

​Query Parameters

​Response

Build docs developers (and LLMs) love

Overview

Batch Features

Create Batch

Request Body

Response

Batch Size Limits

Get Batch Status

Response

Errors

Get Batch with Jobs

Response

List Batches

Query Parameters

Response

Cancel Batch

Request Body

Response

Get Batch Statistics

Response

Get Usage Status

Response

Get Usage History

Query Parameters

Response