---
title: "Run Batch Simulation"
method: POST
path: "/projects/{project_id}/simulation"
tags: ["Simulations"]
---

# Run Batch Simulation

`POST /projects/{project_id}/simulation`

## Request

- Base URL: `https://api.puppeteerai.com`
- URL: `https://api.puppeteerai.com/projects/{project_id}/simulation`
- Auth: none declared. Required headers: `Authorization`

Start a batch conversation simulation for a specific project.

This endpoint starts a background simulation and returns immediately with a simulation ID.

Args:
    project_id: ID of the project/config to use for simulation
    request: Batch simulation configuration
    background_tasks: FastAPI background tasks
    organization: Authenticated organization

Returns:
    BatchSimulationResponse with simulation ID and status

Raises:
    HTTPException: If validation fails

## Path parameters

- `project_id` string, required

## Headers

- `Authorization` string, required

## Request body

- BatchSimulationRequest: Request model for batch conversation simulation.
  - `is_voice` boolean: Whether to run in voice mode
  - `call_direction` 'inbound' | 'outbound', nullable: Fake the call direction for voice runs so configs branching on <<call_direction>> can be tested
  - `prompts` PromptItem[], required: List of prompts (content + optional name); 1-10 items
    - `content` string, required: Persona description (AI prompt)
    - `name` string, nullable: Optional label for this simulation
  - `batch_size` integer, required: Number of simulation runs per prompt (max 20)
  - `user_messages` string[], nullable: List of user messages to send in each conversation
  - `json_data_list` JsonDataItem[]: List of JSON data variants (min 0 = no JSON, max 20); each has content and optional name
    - `content` object, required: JSON payload for thread initialization
    - `name` string, nullable: Optional label for this variant (used in simulation name when multiple variants exist)
  - `turn_count` integer, required: Maximum number of turns (AI responses) per conversation (max 30)
  - `temperature` number, nullable: Model temperature for randomness control (canonical scale 0-1)
  - `max_concurrent_simulations` integer: Maximum number of simulations to run concurrently (default 10, max 50)
  - `mock_responses` object, nullable: Mock responses for HTTP services during simulation
  - `message_delay` number, nullable: Delay in seconds between simulation messages (default 2.0, 0 = no delay)
  - `persona_model` string, nullable: Model to use for persona message generation (default: gpt-5.6-luna)
  - `llm_model` string, nullable: Override the project LLM model for this simulation
  - `env_variables` object, nullable: Environment variable overrides for this simulation
  - `env_secrets` object, nullable: Environment secret overrides for this simulation
  - `tracing_enabled` boolean: Enable LangSmith tracing for all threads in this simulation
  - `retell_account_id` string, nullable: Retell account to use for voice simulations; required when the project has multiple voice integrations

## Response `200`

Successful Response

- BatchSimulationResponse: Response model for batch conversation simulation.
  - `simulation_id` string, required
  - `status` string, required
  - `message` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/getpuppeteer/apis/puppeteer-core-api.md) - [All operations](https://skmtc.dev/getpuppeteer/apis/puppeteer-core-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpuppeteer/apis/puppeteer-core-api/revisions/94b4e928b42f?raw)