# Create simulation (/docs/api-reference/simulation/createSimulation)

> Create a new test simulation with scenarios.



**POST** `/simulations`

Create a new test simulation with scenarios.

```yaml
operationId: createSimulation
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - name
          - agent_id
        properties:
          name:
            type: string
            description: Name of the simulation.
            example: My Simulation
          agent_id:
            type: integer
            description: ID of the agent to test.
            example: 158910
          number_of_call_to_make:
            type: integer
            default: 1
            minimum: 1
            maximum: 3
            description: Number of calls to make per scenario (default 1, max 3).
          concurrent_call_count:
            type: integer
            default: 3
            minimum: 1
            maximum: 3
            description: Number of concurrent calls to run (default 3, max 3).
          max_call_duration_in_minutes:
            type: integer
            default: 3
            minimum: 1
            maximum: 10
            description: Maximum duration for each call in minutes (default 3, max 10).
          scenarios:
            type: array
            description: List of test scenarios to execute.
            items:
              type: object
              required:
                - name
                - description
                - expected_result
              properties:
                name:
                  type: string
                  description: Name of the test scenario.
                  example: Polite cancellation
                description:
                  type: string
                  description: Detailed instructions for the test scenario.
                  example: Ask to cancel a subscription, but be friendly.
                expected_result:
                  type: string
                  description: Expected outcome or behavior from the agent.
                  example: Agent acknowledges the request and routes to retention.
                selected_voices:
                  type: array
                  description: >-
                    Voice configurations for the test calls. If multiple voices are selected, the
                    agent randomly picks one per call per scenario.
                  items:
                    type: object
                    required:
                      - id
                      - provider
                    properties:
                      id:
                        type: string
                        description: Voice ID from the provider.
                      provider:
                        type: string
                        enum:
                          - eleven_labs
                          - play_ht
                          - deepgram
                          - cartesia
                          - rime
                        example: eleven_labs
responses:
  '200':
    description: Simulation created.
    content:
      application/json:
        schema:
          type: object
          properties:
            success:
              type: boolean
            simulation:
              type: object
              description: A test simulation for an agent.
              properties:
                id:
                  type: integer
                  example: 772
                name:
                  type: string
                bot_id:
                  type: object
                  description: The agent under test.
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
                status:
                  type: string
                  enum:
                    - Draft
                    - Pending
                    - In Progress
                    - Calculating Summary
                    - Completed
                    - Stopped
                number_of_call_to_make:
                  type: integer
                concurrent_call_count:
                  type: integer
                max_call_duration_in_minutes:
                  type: integer
                scenarios_ids:
                  type: array
                  description: Scenario records attached to this simulation.
                  items:
                    type: object
                    additionalProperties: true
                what_went_wrong:
                  oneOf:
                    - type: string
                    - type: boolean
                suggestions_for_improvement:
                  oneOf:
                    - type: string
                    - type: boolean
                prompt_suggestion:
                  oneOf:
                    - type: string
                    - type: boolean
                is_auto_prompt_suggestions_applied:
                  type: boolean
                how_many_scenario_to_generate:
                  type: integer
                summary:
                  oneOf:
                    - type: string
                    - type: boolean
                analyticsData:
                  type: object
                  properties:
                    Positive:
                      type: integer
                    Negative:
                      type: integer
                    Neutral:
                      type: integer
                total_simulation_remaining_records:
                  type: integer
                total_simulation_in_progress_records:
                  type: integer
                total_simulation_finished_records:
                  type: integer
                total_records:
                  type: integer
                progress:
                  type: array
                  minItems: 1
                  maxItems: 1
                  items:
                    type: integer
                  description: >-
                    Single-element array containing the progress percentage (0-100). Quirky shape
                    preserved for backwards compatibility.
                  example:
                    - 0
                simulation_call_recording:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
                can_stop:
                  type: boolean
                active_calls_count:
                  type: integer
                create_date:
                  type: string
                  example: 05/06/2026 13:31:54
        example:
          success: true
          simulation:
            id: 456
            name: Customer Support Test
            bot_id:
              id: 1234
              name: Customer Support Agent
            scenarios_ids: []
            status: Draft
            number_of_call_to_make: 1
            concurrent_call_count: 3
            max_call_duration_in_minutes: 3
            what_went_wrong: false
            suggestions_for_improvement: false
            prompt_suggestion: false
            is_auto_prompt_suggestions_applied: false
            how_many_scenario_to_generate: 0
            summary: false
            analyticsData:
              Positive: 0
              Negative: 0
              Neutral: 0
            total_simulation_remaining_records: 0
            total_simulation_in_progress_records: 0
            total_simulation_finished_records: 0
            total_records: 0
            progress:
              - 0
            create_date: 05/08/2026 09:10:29
            simulation_call_recording: []
            can_stop: false
            active_calls_count: 0
```

**Python SDK**

```python
from omnidimension import Client
client = Client(api_key)

# Create a basic simulation
response = client.simulation.create(
    name="Restaurant Order Taking Test",
    agent_id=123,
    number_of_call_to_make=1,
    concurrent_call_count=3,
    max_call_duration_in_minutes=3,
    scenarios=[
        {
            "name": "Order Pizza",
            "description": "1. Act as a customer wanting to order pizza\n2. Ask for menu items\n3. Order a large pepperoni pizza\n4. Provide contact details\n5. End call with thank you",
            "expected_result": "Order should be placed successfully and confirmation provided",
            "selected_voices": [
                {"id": "voice_id_1", "provider": "eleven_labs"},
                {"id": "voice_id_2", "provider": "play_ht"}
            ]
        }
    ]
)
print(response)
```

**curl**

```bash
curl -X POST "https://backend.omnidim.io/api/v1/simulations" \
  -H "Authorization: Bearer $OMNIDIM_API_KEY"
```