---
title: "Create Simulation"
method: POST
path: "/v1/create-simulation"
tags: ["Simulations"]
---

# Create Simulation

`POST /v1/create-simulation`

Create a new simulation with the provided details.

Returns the simulation id and a status code.

## Headers

- `X-API-Key` string, required

## Request body

- SimulationRequest — Pydantic model for simulation request
  - `agent_id` string, required — ID of the agent to be used in the simulation
  - `name` string, nullable — Name of the simulation
  - `description` string, nullable — Description of the simulation
  - `prompt_id` string, uuid, nullable — Optional default prompt UUID for this simulation
  - `knowledge_base_id` string, uuid, nullable — Optional default knowledge base UUID for this simulation
  - `max_concurrent` integer, nullable — Maximum number of concurrent calls in the simulation (max 500)
  - `hangup_on_transfer` boolean, nullable — Whether to hang up the call on transfer
  - `max_call_duration` integer, nullable — Maximum duration of each call (default is 10). Units specified by max_call_duration_units
  - `max_call_duration_units` 'minutes' | 'seconds', nullable — Units for max_call_duration: 'minutes' (default) or 'seconds'
  - `ringing_timeout` integer, nullable — Ringing timeout in seconds for SIP trunks (default 300s)
  - `digital_humans_settings` DigitalHumansSettings — Pydantic model for digital humans settings in simulation
    - `default_name` string, nullable — Default name for the digital human
    - `default_caller_number` string, nullable — Default caller phone number for the digital human
    - `default_language` string, nullable — Default language for the digital human
    - `default_background_noise` string, nullable — Background noise to be used in the simulation
    - `first_message` string, nullable — First message to be spoken by the digital human
    - `num_runs` integer, nullable — Number of runs per digital human per simulation run (run count).
  - `selected_custom_metrics` string[], nullable — Custom metric IDs to enable for this simulation
  - `custom_metrics_failing_threshold` integer, nullable — Score threshold below which a custom metric is considered failing (0-100)
  - `custom_metrics_passing_threshold` integer, nullable — Score threshold at or above which a custom metric is considered passing (0-100)
  - `runs_per_digital_human` integer, nullable — Number of simulation runs to execute per digital human (defaults to 1 when omitted)
  - `delay_between_tests_seconds` number, nullable — seconds to wait after a test completes before the next launches (0 = off)
  - `inactivity_timeout_seconds` integer, nullable — seconds to wait for an agent reply before ending a text conversation (300-1800 = 5-30 min); defaults to 300 when unset
  - `always_on` boolean, nullable — When true, simulation has always-on digital humans configured

## Response `200`

Successful Response

- SimulationResponse
  - `simulation_id` integer, required — ID of the created simulation
  - `status` string — Status of the response

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/getbluejay/apis/bluejay-api.md) · [All operations](https://skmtc.net/getbluejay/apis/bluejay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbluejay/bluejay-api/revisions/18bc44e35414/schema)