> ## Documentation Index
> Fetch the complete documentation index at: https://docs.60db.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Simulation

> Start AI-to-AI test calls against an agent. Every call spends real credits, up to a ceiling you set

> [!NOTE]
>
> AI Simulation needs an active **Pro** or **Business** plan. On another plan, every simulation endpoint returns `403 POLICY_DENY`.

Start a simulation. AI callers phone your agent and each call is judged. Use `mode: "generate"` to let the agent's model write the stories, or `mode: "custom"` to send your own story.

> [!WARNING]
>
> Simulated calls spend real credits. A request without `max_credits` and `estimated_credits_per_call` is refused. One request may queue at most 1,000 calls (stories × repeats). A workspace can have 3 active runs at once.

The run starts at once. Read it with [Get simulation](https://docs.60db.ai/api-reference/agents/get-simulation.md). For the full flow, see [Reliability and simulation](https://docs.60db.ai/features/agents-reliability.md).

## Request

### Headers

**Authorization** `string` *required*

Bearer token with your API key (scope `agents`)

**Content-Type** `string` *required*

application/json

### Path

**agentId** `string` *required*

The agent `id` (UUID). The agent must be in your workspace and saved at least once

### Body

**mode** `string` *required*

`generate` or `custom`

**count** `integer` (default: 12)

`generate` only. 9 to 50. How many stories the agent's model writes. This makes one paid model request before the run is queued

**sample\_rate** `integer` (default: 8000)

`generate` only. `8000`, `16000` or `24000`

**scenario** `object` *required*

`custom` only. One story: `name`, `persona`, `steps`, `checks`, `entities` and `tool_answers`. `steps` and `checks` are checked by the voice service. Each check item is `{ "check": { "check": "contains", "arg": "balance" }, "must_pass": true }`. The story must answer every tool of the agent in `tool_answers`, or the start answers `400` with `field: "tool_answers"`. A mistake returns `400` with the `field` name. See [Write a story](https://docs.60db.ai/features/agents-reliability.md#write-a-story)

**max\_credits** `number` *required*

The credit ceiling. The run stops when it reaches this many credits and ends in the state `stopped_budget` with a partial report. Must be more than 0

**estimated\_credits\_per\_call** `number` *required*

Your estimate of the credits one simulated call uses. Must be more than 0. 60db checks your balance for the lower of `max_credits` and `estimated_credits_per_call` × the number of calls before anything is queued

**repeats** `integer` (default: 1)

1 to 100. How many times each story runs

**priority** `string` (default: manual)

`manual`, or `ci`. `ci` is only for API keys. Dashboard sessions that send `ci` get `400`

**max\_concurrency** `integer`

1 to 20. How many simulated calls run at once

**max\_calls** `integer`

At least 1. Stop after this many calls

**max\_minutes** `integer`

At least 1. Stop after this many minutes of calls

**baseline\_run\_id** `string`

A run to compare with

## Response

**201 Created**.

```json theme={null}
{
  "run_id": "6f1c1e2a-3333-4000-8000-000000000001",
  "total": 24,
  "state": "running",
  "estimate": { "calls": 24, "minutes_upper_bound": 120, "credits": 12, "credits_per_call": 0.5 },
  "scenarios": [{ "name": "caller-gives-account-number", "coverage": "account numbers" }]
}
```

`run_id` is 60db's ID. Use it in all other simulation routes. `scenarios` is only in `generate` mode.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `VALIDATION_ERROR` | A field is missing or wrong. `field` names it. `max_credits` and `estimated_credits_per_call` are required |
| 400 | `SIMULATION_TOO_LARGE` | More than 1,000 calls in one request |
| 402 | `INSUFFICIENT_CREDITS` | The balance cannot cover the run. Nothing was queued |
| 403 | `POLICY_DENY` | Your role cannot run simulations (owner, admin or developer), the workspace is not on an active Pro or Business plan, or the API key lacks the `agents` scope |
| 404 | `AGENT_NOT_FOUND` | No agent with this ID in your workspace |
| 409 | `AGENT_NOT_SYNCED` | Save the agent once, then try again |
| 422 | `SIMULATION_GENERATION_FAILED` | The model wrote unusable stories. Nothing was queued. Try again |
| 429 | `TOO_MANY_RUNS` | A simulation is already running or paused in this workspace (one runs at a time), or the voice service is busy |
| 429 | `RATE_LIMITED` | More than 5 starts a minute |
| 503 | `SIMULATION_UNAVAILABLE` | The simulation queue is not available. Try again shortly |
| 504 | `SIMULATION_TIMEOUT` | Story generation took too long. Check [List simulations](https://docs.60db.ai/api-reference/agents/list-simulations.md) before you try again |

## Example

```bash cURL theme={null}
curl -X POST https://api.60db.ai/agents/AGENT_ID/simulations \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"mode": "generate", "count": 12, "repeats": 2, "max_credits": 20, "estimated_credits_per_call": 0.5}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.