# Run a simulation

Source: https://langbot.ai/docs/api/sim/create-run

`POST /v1/sim/runs`

Replay a past event against its recorded order books with a built-in strategy, at several latencies, and get the scorecard.

**Auth.** An API token: `Authorization: Bearer lb_…` ([create one](https://langbot.ai/app/tokens)). Signed-in web sessions work too.

**Limits.** One Sim run (20 a month on Free, 100 on Builder, unlimited on Standard).

## Parameters

### Body

| Name | Type | Required | Description |
|---|---|---|---|
| `event_id` | string | yes | A replayable event (`ev_…`); see [List replayable events](https://langbot.ai/docs/api/sim/list-replayable-events). |
| `strategy` | string | no | A built-in strategy name; see [List built-in strategies](https://langbot.ai/docs/api/sim/list-strategies). Default `hold_none`. |
| `params` | object | no | The strategy's parameters; unknown names are refused. |
| `latency_ms` | array of integer | no | Milliseconds after each event's emission to evaluate fills at, up to 6 values; default `[250, 2250, 5250]`. |
| `starting_cash` | number | no | Paper cash in USD. Up to 10,000,000. Default `1000.0`. |
| `maker_fee_rate` | number | no | The maker fee rate. 0 to 0.5. Default `0.0175`. |
| `queue_position` | boolean | no | Make resting orders wait behind the size recorded at their price. Default `false`. |
| `taker_delay_ms` | integer | no | A venue speed bump on taking orders, in ms. 0 to 60,000. Default `0`. |
| `code` | string | no | Refused. Your own strategy files run on your machine with `langbot sim run -s my_bot.py`. |

## Request

**curl**

```bash
curl -X POST "https://api.langbot.ai/v1/sim/runs" \
  -H "Authorization: Bearer $LANGBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "ev_kxearningsmentiongs_26oct13", "strategy": "buy_yes_on_first_counting_hit", "params": {"max_price": 0.6}}'
```

**Python**

```python
from langbot import LangbotClient

async with LangbotClient() as lb:  # reads LANGBOT_API_TOKEN
    run = await lb.sim_run(
        "ev_kxearningsmentiongs_26oct13",
        "buy_yes_on_first_counting_hit",
        params={"max_price": 0.6},
    )
    print(run["id"], run["scorecard"]["by_latency"])
```

**TypeScript**

```ts
const res = await fetch("https://api.langbot.ai/v1/sim/runs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.LANGBOT_API_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({"event_id": "ev_kxearningsmentiongs_26oct13", "strategy": "buy_yes_on_first_counting_hit", "params": {"max_price": 0.6}}),
});
console.log(await res.json());
```

## Response

`201 Created`

```json
{
  "id": "run_01K8Z3…",
  "kind": "server",
  "event_id": "ev_kxearningsmentiongs_26oct13",
  "strategy": "buy_yes_on_first_counting_hit",
  "params": { "max_price": 0.6 },
  "latency_ms": [250, 2250, 5250],
  "starting_cash": 1000.0,
  "paid": false,
  "created_at": 1793500000000,
  "scorecard": {
    "books_replayed": 18342,
    "by_latency": [
      { "latency_ms": 250, "net": 41.2, "fees": 3.1, "fills": 4, "fill_rate": 1.0, "max_drawdown": 6.0 },
      { "latency_ms": 2250, "net": 18.7, "fees": 3.3, "fills": 4, "fill_rate": 1.0, "max_drawdown": 9.5 },
      { "latency_ms": 5250, "net": -4.9, "fees": 2.4, "fills": 3, "fill_rate": 0.75, "max_drawdown": 14.0 }
    ],
    "markets": []
  },
  "allowance": { "plan": "free", "runs": 20, "period": "month", "used": 3, "remaining": 17, "resets_at": 1793577600000 }
}
```

A scorecard describes what the strategy would have done against the recorded books, after the venue's fees; it is not a forecast. How fills and fees are modelled: [Simulator and backtesting](https://langbot.ai/docs/backtesting).

## Errors

| Status | `code` | When |
|---|---|---|
| 400 | `bad_request` | The body carries `code`: custom strategies run locally. |
| 404 | `not_found` | No recorded feed or no order books for the event. |
| 413 | `too_large` | Over 5 million book snapshots in the window; run it locally. |
| 401 | `auth_required` | No token was sent. |
| 401 | `token_invalid` | The token was not recognised (mistyped, revoked or expired). |
| 422 | `validation_error` | A parameter failed validation; `detail[].loc` names it. |
| 429 | `quota_exceeded` | This month's Sim runs are spent; `quota.resets_at` says when they reset. |
| 429 | `rate_limited` | Over your request budget; wait `Retry-After` seconds. |

Every error body is `{"detail": …, "code": "…"}`; branch on `code`. All codes: [Errors](https://langbot.ai/docs/api#errors).