---
title: "Backtest a workflow definition"
method: POST
path: "/simulate"
tags: ["Execution Engine"]
---

# Backtest a workflow definition

`POST /simulate`

## Request

- Base URL: `https://api.indexone.io`
- URL: `https://api.indexone.io/simulate`
- Auth: API key in header `x-api-key`

Launches a historical simulation of an index definition and returns a pollable backtest id immediately — the same launch-now/fetch-later shape as the MCP `run_backtest` tool. The run replays the DAG over every scheduled date from `start_time` to now; its value series, holdings and statistics are persisted to a backtest blob. Nothing live is created and no schedule is registered.

The body is `{"index_parameters": {...}}` — the same object `POST /workflows` would take.

Fetch the result from `GET /backtests/{backtest_id}`, which waits server-side for the in-flight window so polling straight after this call is fine. Optionally pass `websocket_id` (or `connection_id`) to *also* stream progress frames over the WebSocket API as the run computes.

Because the id comes back at once, the 29-second API Gateway integration timeout can never sever the launch. This route runs a backtest only — `stage` is forced to `backtest`; creating a live index is `POST /workflows`. Requires a team API key.

## Request body

- object
  - `index_parameters` object, required: The workflow definition: `name`, `start_time`, `exchange_calendar`, `operations`.
  - `websocket_id` string: Stream results to this WebSocket connection and return immediately. Also accepted as `connection_id`.

## Response `200`

The backtest was accepted and is running. Poll `GET /backtests/{backtest_id}` for the result; `connection_id` is echoed when `websocket_id` was supplied.

- object
  - `ok` boolean
  - `backtest_id` string
  - `status` 'running'
  - `hint` string
  - `connection_id` string

## Other responses

- `400`: No `index_parameters` object in the request body.
- `403`: Missing or invalid API key.
- `422`: The request body failed validation before the backtest was built.
- `500`: The backtest raised.

---

[API](https://skmtc.dev/indexone/apis/index-one-rest-api.md) · [All operations](https://skmtc.dev/indexone/apis/index-one-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/indexone/apis/index-one-rest-api/revisions/df5a92216a9c?raw)