GEgetpuppeteer
Simulations

Run Batch Simulation

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

post/projects/{project_id}/simulation

Request

  • Base URL
    https://api.puppeteerai.com
  • Auth
    none declared. Required headers: Authorization

Path parameters

project_idstring required

Headers

Authorizationstring required

Request body

is_voiceboolean

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

batch_sizeinteger required

Number of simulation runs per prompt (max 20)

user_messagesstring[] nullable

List of user messages to send in each conversation

turn_countinteger required

Maximum number of turns (AI responses) per conversation (max 30)

temperaturenumber nullable

Model temperature for randomness control (canonical scale 0-1)

max_concurrent_simulationsinteger

Maximum number of simulations to run concurrently (default 10, max 50)

mock_responsesobject nullable

Mock responses for HTTP services during simulation

message_delaynumber nullable

Delay in seconds between simulation messages (default 2.0, 0 = no delay)

persona_modelstring nullable

Model to use for persona message generation (default: gpt-5.6-luna)

llm_modelstring nullable

Override the project LLM model for this simulation

env_variablesobject nullable

Environment variable overrides for this simulation

env_secretsobject nullable

Environment secret overrides for this simulation

tracing_enabledboolean

Enable LangSmith tracing for all threads in this simulation

retell_account_idstring nullable

Retell account to use for voice simulations; required when the project has multiple voice integrations

Response

Successful Response

simulation_idstring required
statusstring required
messagestring required

Changes

No recorded changes to this operation across all 1 revision of this API.