> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# Manage simulations

> Manage Vapi simulation suites and runs: edit configurations, review and rerun results, develop testing strategies, maintain coverage, and delete suites.

Manage an existing simulation suite from the Dashboard or API. You can duplicate or edit its configuration, review and rerun results, cancel an active run, maintain test coverage, or delete the suite. If you have not created a suite, complete the [**Simulations quickstart**](/observability/simulations-quickstart) first.

## Edit a suite

#### Dashboard

Open **Simulations**, select **Suites**, and open the suite. Select **Edit** in the top-right corner, change its simulations, scenarios, personalities, or success criteria, then save.

#### cURL

Update a suite with `PATCH`. Send only the fields you want to change. For example, rename it or change which simulations it includes.

```bash
curl -X PATCH "https://api.vapi.ai/eval/simulation/suite/<suite-id>" \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renamed suite", "simulationIds": ["<simulation-id>"] }'
```

To edit a scenario, personality, or simulation directly, use their own `PATCH` endpoints: `/eval/simulation/scenario/{id}`, `/eval/simulation/personality/{id}`, and `/eval/simulation/{id}`.

## Duplicate a suite

Duplicating a suite creates an independent copy of its simulations, targets, and notification settings. The duplicate uses the original suite name with `(copy)` appended, and later changes do not affect the original suite.

#### Dashboard

Open **Simulations**, select **Suites**, and open the suite. Open the suite actions menu, select **Duplicate**, then confirm. Vapi opens the duplicate after creating it.

#### cURL

Duplicate a suite with `POST`. The request does not require a body.

```bash
curl -X POST "https://api.vapi.ai/eval/simulation/suite/<suite-id>/duplicate" \
  -H "Authorization: Bearer $VAPI_API_KEY"
```

The response contains the new simulation suite.

## Rename an AI tester

You cannot rename an AI tester from the Dashboard. An AI tester's name comes from its personality, so rename the tester with the API by updating the personality with `PATCH`. Send only the `name` field.

```bash
curl -X PATCH "https://api.vapi.ai/eval/simulation/personality/<personality-id>" \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New tester name" }'
```

## Review run results

#### Dashboard

Open **Simulations**, then select **Runs** to see every run with its suite, iterations, [**assistant**](/assistants) or [**squad**](/squads), run date, and overall result (`Passed` or a failed count such as `1/1 failed`). Filter by **time range**, **status**, or **assistant or squad** to find a run.

Open a run to see whether each simulation passed or failed, its evaluations, its latency results for voice runs, and its transcript. Open an active run to watch the transcript and evaluations update. If a run or iteration can't complete, it shows a **Failure reason** describing what went wrong, such as no payment method on file. See the [**Simulations quickstart**](/observability/simulations-quickstart) for the full walkthrough.

#### cURL

List runs, then fetch one for its status and results.

```bash
curl -X GET "https://api.vapi.ai/eval/simulation/run" \
  -H "Authorization: Bearer $VAPI_API_KEY"
```

```bash
curl -X GET "https://api.vapi.ai/eval/simulation/run/<run-id>" \
  -H "Authorization: Bearer $VAPI_API_KEY"
```

The run includes `status` and `itemCounts` (`total`, `passed`, `failed`, and so on). Fetch the result for each simulation iteration with `GET /eval/simulation/run/<run-id>/item`. Each item's `results` holds its `evaluations` and, when the scenario sets latency limits, its `latencyEvaluations`. See [**Review latency results**](/observability/simulations-advanced#review-latency-results).

## Rerun a suite

#### Dashboard

Open **Simulations**, select **Runs**, and find the completed run. Select **Rerun**, choose the **Mode** (chat or voice) and **Iterations**, then confirm. Each rerun creates a new run that you can compare with previous results.

#### cURL

Rerunning is just a new run. Call the run endpoint again with the same suite.

```bash
curl -X POST "https://api.vapi.ai/eval/simulation/run" \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "simulations": [{ "type": "simulationSuite", "simulationSuiteId": "<suite-id>" }],
    "target": { "type": "assistant", "assistantId": "<assistant-id>" },
    "transport": { "provider": "vapi.webchat" },
    "iterations": 1
  }'
```

Use `"provider": "vapi.websocket"` for voice.

## Testing strategies

Build coverage gradually as the assistant or squad changes.

### Smoke tests

Start with a core path, a direct intent, and one or two required Boolean evaluations. One iteration is useful while setting up or debugging the test, not as evidence of reliability. Repeat critical release checks based on risk and past variation. Chat mode gives quick feedback on conversation and tool logic.

### Regression tests

Create a regression test when you fix a defect or find an unexpected response. Reproduce the original conditions in the scenario, give the simulation a descriptive name, and keep it in the suite that covers the affected behavior.

### Edge-case tests

Test realistic variations such as an ambiguous request, an impatient customer, an unavailable appointment, a tool error, an interruption, or a handoff. Base AI tester personalities on the customer types the [**assistant**](/assistants) or [**squad**](/squads) handles. Synthetic callers don't reliably reproduce every interruption, silence, or background-noise condition. Keep controlled real-call checks for problems the simulation can't reproduce.

### Design evaluations

Keep each evaluation focused on one observable outcome. Use a descriptive name, choose a Boolean or numeric value that can be measured consistently, and avoid combining several independent requirements into one evaluation.

To catch slow responses, add a [**latency limit**](/observability/simulations-advanced#set-latency-limits) rather than an evaluation, and run the suite in voice mode. Median turn latency is the most stable limit to gate a release on.

### Choose voice or chat mode

| Testing goal                                                   | Mode                     | Why                                                                                                   |
| -------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| Iterate on prompts, tools, and conversation logic              | Chat (`vapi.webchat`)    | Runs without audio processing, so it is faster and costs less.                                        |
| Investigate speech recognition, voice output, or interruptions | Voice (`vapi.websocket`) | Exercises synthetic audio. Review the recording, not just the pass/fail label.                        |
| Gate on response latency                                       | Voice (`vapi.websocket`) | Latency limits are skipped in chat mode.                                                              |
| Receive call-specific webhook data                             | Voice (`vapi.websocket`) | Start and end webhooks fire in both modes, but chat payloads omit call-specific fields.               |
| Check representative voice journeys before launch              | Voice (`vapi.websocket`) | Adds voice coverage. Also make controlled calls through the real phone path and sandbox integrations. |

Review failures and sample passing runs. Compare automated judgments with human-reviewed examples, and listen to voice recordings when available. Follow [run and maintain tests](/test/run-and-maintain-tests) for release checks and failure triage.

## Maintain simulation coverage

Update simulations when the behavior under test changes:

| Change                                | Action                                                                                   |
| ------------------------------------- | ---------------------------------------------------------------------------------------- |
| Prompt, tool, or configuration update | Rerun the affected suite. Change its evaluations only when the expected outcome changes. |
| New feature or conversation path      | Add simulations for the core path and important failure paths.                           |
| Fixed defect                          | Add a regression simulation that reproduces the original failure.                        |
| New customer behavior or edge case    | Add a representative scenario and AI tester personality.                                 |
| Changed business requirement          | Update the scenario intent and evaluations to describe the new expected outcome.         |

## Cancel a run

Cancel a run while it is still `queued` or `running`.

#### Dashboard

While a run is `queued` or `running`, open **Simulations**, select **Runs**, and open the run. Select **Cancel** in the top-right corner.

#### cURL

Cancel a run with `PATCH` (no body):

```bash
curl -X PATCH "https://api.vapi.ai/eval/simulation/run/<run-id>" \
  -H "Authorization: Bearer $VAPI_API_KEY"
```

To cancel one simulation iteration instead, use `PATCH /eval/simulation/run/<run-id>/item/<item-id>`.

## Delete a suite

> **Warning**
>
> Deleting a suite is permanent and cannot be undone.

#### Dashboard

Open **Simulations**, select **Suites**, and open the suite. Select the **trash** icon in the top-right corner, then confirm the deletion.

#### cURL

Delete a suite with `DELETE`:

```bash
curl -X DELETE "https://api.vapi.ai/eval/simulation/suite/<suite-id>" \
  -H "Authorization: Bearer $VAPI_API_KEY"
```

Personalities, scenarios, and simulations have their own `DELETE` endpoints: `/eval/simulation/personality/{id}`, `/eval/simulation/scenario/{id}`, and `/eval/simulation/{id}`. Runs are canceled, not deleted.

## Next steps

#### [Simulations overview](/observability/simulations-overview)

Learn what Simulations are and when to use them instead of Evals.

#### [Simulations quickstart](/observability/simulations-quickstart)

Create and run your first simulation suite.

#### [Simulations advanced](/observability/simulations-advanced)

Configure variables, tool mocks, webhooks, and structured outputs.

#### [Configure an AI tester](/observability/simulations-configure-ai-tester)

Define the AI tester's scenario, behavior, model, transcriber, and voice.