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

# Run Single Simulation

`POST /projects/{project_id}/single-simulation`

## Request

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

Start a single conversation simulation for a specific project.
This endpoint creates a new thread, returns the thread_id immediately, and runs the simulation in the background.
The simulation will stream messages to the websocket as it progresses.

## Path parameters

- `project_id` string, required

## Headers

- `Authorization` string, required

## Request body

- SingleSimulationRequest: Request model for single 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
  - `ai_prompt` string, required: AI system prompt to use
  - `user_messages` string[], nullable: List of user messages to send in the conversation
  - `json_data` object, nullable: Initial JSON data for the thread
  - `turn_count` integer, required: Maximum number of turns (AI responses) per conversation (max 30)
  - `thread_id` string, required: Thread ID to use for the simulation
  - `temperature` number, nullable: Model temperature for randomness control (canonical scale 0-1)
  - `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)
  - `env_variables` object, nullable: Environment variable overrides for this simulation
  - `env_secrets` object, nullable: Environment secret overrides for 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

- SingleSimulationResponse: Response model for single conversation simulation.
  - `thread_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)