Skip to main content

​
Overview

The Simulations API allows you to create, monitor, and manage simulation jobs. Simulations run asynchronously and can be tracked via status polling.

​
Job Lifecycle

  1. PENDING - Job created and queued
  2. RUNNING - Job is executing
  3. COMPLETED - Job finished successfully
  4. FAILED - Job encountered an error
  5. CANCELLED - Job was cancelled by user

​
Create Simulation

Create a new simulation job. The job runs asynchronously in the background.
POST /simulations
curl -X POST http://localhost:8080/simulations \
  -H "X-API-Key: tp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "board_meeting",
    "entity_count": 5,
    "timepoint_count": 10,
    "temporal_mode": "FORWARD",
    "description": "Board meeting simulation"
  }'

​
Request Body

​
template_id
string
required
Template ID (see /simulations/templates)
​
entity_count
integer
Number of entities (uses template default if not provided)
​
timepoint_count
integer
Number of timepoints (uses template default if not provided)
​
temporal_mode
string
Temporal mode: FORWARD, PORTAL, BRANCHING, DIRECTORIAL, or CYCLICAL
​
description
string
Human-readable description
​
config
object
Custom simulation configuration (overrides template defaults)

​
Response

Status: 202 Accepted
​
job_id
string
Unique job identifier
​
status
string
Current status (PENDING)
​
created_at
string
Creation timestamp
​
template_id
string
Template used
​
description
string
Job description
​
entity_count
integer
Number of entities
​
timepoint_count
integer
Number of timepoints
​
temporal_mode
string
Temporal mode
​
owner_id
string
User who created the job
{
  "job_id": "job-abc123def456",
  "status": "PENDING",
  "created_at": "2026-03-06T12:00:00Z",
  "started_at": null,
  "completed_at": null,
  "template_id": "board_meeting",
  "description": "Board meeting simulation",
  "entity_count": 5,
  "timepoint_count": 10,
  "temporal_mode": "FORWARD",
  "progress_percent": 0,
  "current_step": null,
  "run_id": null,
  "entities_created": 0,
  "timepoints_created": 0,
  "cost_usd": 0.0,
  "tokens_used": 0,
  "error_message": null,
  "owner_id": "user-123"
}

​
Rate Limits

  • Free: 1 concurrent job
  • Basic: 3 concurrent jobs
  • Pro: 10 concurrent jobs
  • Enterprise: Unlimited

​
Get Simulation

Get details about a specific simulation job.
GET /simulations/{job_id}
curl -X GET http://localhost:8080/simulations/job-abc123def456 \
  -H "X-API-Key: tp_your_api_key_here"

​
Response

Returns a job object with updated status and progress information. 
{
  "job_id": "job-abc123def456",
  "status": "RUNNING",
  "created_at": "2026-03-06T12:00:00Z",
  "started_at": "2026-03-06T12:00:05Z",
  "completed_at": null,
  "template_id": "board_meeting",
  "description": "Board meeting simulation",
  "entity_count": 5,
  "timepoint_count": 10,
  "temporal_mode": "FORWARD",
  "progress_percent": 45,
  "current_step": "Generating dialog for timepoint 5",
  "run_id": "run-2026-03-06-120005",
  "entities_created": 5,
  "timepoints_created": 4,
  "cost_usd": 0.03,
  "tokens_used": 1500,
  "error_message": null,
  "owner_id": "user-123"
}

​
Errors

  • 404 Not Found - Job doesn’t exist
  • 403 Forbidden - Not the job owner

​
List Simulations

List your simulation jobs with optional filtering.
GET /simulations
curl -X GET "http://localhost:8080/simulations?status=RUNNING&page=1&page_size=20" \
  -H "X-API-Key: tp_your_api_key_here"

​
Query Parameters

​
status
string
Filter by status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
​
page
integer
default:"1"
Page number
​
page_size
integer
default:"20"
Jobs per page (1-100)

​
Response

​
jobs
array
Array of job objects
​
total
integer
Total number of jobs
​
page
integer
Current page
​
page_size
integer
Page size
{
  "jobs": [
    {
      "job_id": "job-abc123",
      "status": "COMPLETED",
      "created_at": "2026-03-06T10:00:00Z",
      "completed_at": "2026-03-06T10:05:30Z",
      "template_id": "board_meeting",
      "description": "Board meeting simulation",
      "cost_usd": 0.05,
      "tokens_used": 2500
    }
  ],
  "total": 15,
  "page": 1,
  "page_size": 20
}

​
Get Simulation Result

Get detailed results for a completed simulation.
GET /simulations/{job_id}/result
curl -X GET http://localhost:8080/simulations/job-abc123def456/result \
  -H "X-API-Key: tp_your_api_key_here"

​
Response

​
job
object
Job metadata
​
entities
array
Created entities (future: will load from database)
​
timepoints
array
Created timepoints (future: will load from database)
​
relationships
array
Entity relationships
​
summary
object
Simulation summary
​
narrative_exports
array
Generated narrative exports
​
convergence_score
number
Simulation convergence score
​
robustness_grade
string
Robustness grade

​
Errors

  • 400 Bad Request - Job is not completed
  • 404 Not Found - Job doesn’t exist
  • 403 Forbidden - Not the job owner

​
Cancel Simulation

Cancel a running or pending simulation.
POST /simulations/{job_id}/cancel
curl -X POST http://localhost:8080/simulations/job-abc123def456/cancel \
  -H "X-API-Key: tp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"reason": "No longer needed"}'

​
Request Body

​
reason
string
Cancellation reason (optional)

​
Response

Returns the job object with status CANCELLED.

​
Errors

  • 400 Bad Request - Job cannot be cancelled (already completed/failed)
  • 404 Not Found - Job doesn’t exist
  • 403 Forbidden - Not the job owner

​
Get Statistics

Get statistics about your simulation jobs.
GET /simulations/stats
curl -X GET http://localhost:8080/simulations/stats \
  -H "X-API-Key: tp_your_api_key_here"

​
Response

​
total_jobs
integer
Total jobs created
​
pending
integer
Jobs pending
​
running
integer
Jobs running
​
completed
integer
Jobs completed
​
failed
integer
Jobs failed
​
cancelled
integer
Jobs cancelled
​
total_cost_usd
number
Total cost across all jobs
​
total_tokens
integer
Total tokens used
{
  "total_jobs": 25,
  "pending": 2,
  "running": 1,
  "completed": 20,
  "failed": 1,
  "cancelled": 1,
  "total_cost_usd": 1.25,
  "total_tokens": 62500
}

​
List Templates

List available simulation templates.
GET /simulations/templates
curl -X GET "http://localhost:8080/simulations/templates?category=showcase" \
  -H "X-API-Key: tp_your_api_key_here"

​
Query Parameters

​
category
string
Filter by category
​
tier
string
Filter by tier (quick/standard/stress)

​
Response

​
templates
array
Array of template objects
​
total
integer
Total template count
​
categories
array
Available categories
{
  "templates": [
    {
      "template_id": "board_meeting",
      "name": "Board Meeting",
      "description": "Corporate board meeting with strategic decisions",
      "category": "showcase",
      "tier": "standard",
      "mechanisms": ["M1", "M7", "M11"],
      "default_entity_count": 5,
      "default_timepoint_count": 8,
      "estimated_cost_usd": 0.05,
      "estimated_duration_seconds": 120
    }
  ],
  "total": 21,
  "categories": ["core", "showcase", "stress"]
}

​
Get Template

Get details about a specific template.
GET /simulations/templates/{template_id}
curl -X GET http://localhost:8080/simulations/templates/board_meeting \
  -H "X-API-Key: tp_your_api_key_here"

​
Response

Returns a template object with all details.

​
Errors

  • 404 Not Found - Template doesn’t exist

Build docs developers (and LLMs) love

Get started for freeTalk to us