Start a backtest
start_backtestStart a new backtest for a revision with the provided date range. ASYNC: This starts a job and returns immediately with a backtest id. backtest_status and artifact tools expose the current state for that id. Backtests are asynchronous and can consume material runtime capacity. Follow the user's instructions about whether to start one. This tool does not create or update visible plan items. Its structured result factually reports the backtest id, revision id, durable external wait id (when created), and Agent run status. Describe only configuration established by the saved revision, submitted parameters or returned result. A start acknowledgment does not establish a restricted seed universe, sampled symbols, completed research, fills or cross-iteration memory. Treat unreturned setup details as unverified; never invent a validation universe that the saved strategy does not define. If revisionId is missing, call list_backtests first and use the Tool IDs section to obtain revisionId/aiStrategyId/strategyId. IMPORTANT: This tool always uses the conversation's configured data provider (defaults to 'botspot_auto' if none is set). Do not call set_data_provider merely to reselect the default. Only when the requested provider is available according to its advertised availability constraints, call set_data_provider first to honor an explicit provider change (inside BotSpot chat you cannot pass a provider directly to this tool). Do not call either tool to probe a provider already declared OFF. Explain that no source changed and no backtest started, offer a supported alternative for the saved assets, and ask which route to use. MCP clients without a BotSpot chat conversation (Claude, ChatGPT, Codex) cannot call set_data_provider; they pass dataProvider (for example alpaca or polygon) on this call instead. The revisionId must be the id from the most recent successful file mutation or readback in this workflow. Every later file mutation supersedes every earlier revision id, even when the later mutation edits the same file. Optional: Provide budget (starting cash) to run the backtest as-if the account started with that amount. This sets BACKTESTING_BUDGET in the backtest environment so it works without modifying strategy code. Use envVarSetIds for saved runtime secrets and data-provider API keys. Do not pass raw env vars, botConfig, API keys, CSV rows, JSON row dumps, workbook data, or inline secret material. Create one saved environment variable at a time with saved_env_vars(action="create") first, then pass returned ids here. Optional: Provide parameters (dict) to override strategy parameters at runtime (e.g. ALLOCATION, symbol, pct_to_trade). BotSpot saves them as an immutable strategy parameter set that can be reused by a backtest or live bot. You may instead pass strategyParameterSetId for this exact saved revision.
IMPORTANT - Handling DATA_ACCESS_REQUIRED errors: If you receive a DATA_ACCESS_REQUIRED or TRIAL_RANGE_EXCEEDED error, this means the user's trial has expired or they need to purchase access. DO NOT attempt to switch to a different data provider (like Polygon or Alpaca) - the user needs to UPGRADE their access to the current provider. Explain that they need to unlock the data add-on for the provider being used (e.g., Theta Data Options). A modal will appear automatically to help them purchase access - do NOT suggest switching providers as a workaround.
IMPORTANT - Handling DATA_PROVIDER_UNAVAILABLE and OPTIONS_DATA_SOURCE_REQUIRED: These mean the data source cannot return data right now (Theta Data is off), so no backtest was started. Do not retry the same backtest. Tell the user plainly what happened and list the alternatives from the result: BotSpot Auto for stocks, indexes, crypto and futures; for options, the user's own connected Alpaca account or their own Polygon API key. On Alpaca or Polygon, index data such as VIX or SPX still works: BotSpot supplies it automatically. When the result has a step marked customerActionNeeded false, do it and start again, then say which data source ran. Otherwise ask which one they want, then call set_data_provider. Never describe this as a problem with their strategy.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"startDate": "<startDate>",
"endDate": "<endDate>"
},
"name": "start_backtest"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cache | No | Market-data cache for this one backtest. Leave unset (or "default") for normal runs. "off" is for measuring cold speed: the run skips the shared market-data cache and fetches from the data provider, so it is slower but the results are the same. backtest_status shows sharedCache "off" for such runs. The data provider may still keep its own caches. | |
| budget | No | Starting cash for the backtest (in the quote currency, typically USD). Sets BACKTESTING_BUDGET in the backtest environment. | |
| endDate | Yes | The last calendar day to simulate, inclusive. Preserve the requested last date; do not add a day as though this were an exclusive upper bound. | |
| profile | No | Set true to profile this backtest with yappi and find where the time goes (slow data calls, slow strategy code). Profiling makes the run slower, so leave it off for normal backtests. When the run finishes, read profile_yappi.csv with get_backtest_artifact and query_csv (columns: full_name, ncall, ttot_s, tsub_s, tavg_s; sort by ttot_s or tsub_s). Only for strategies whose code you own and can see. | |
| startDate | Yes | The first calendar day to simulate, inclusive. Preserve the user-requested date, normally YYYY-MM-DD. | |
| parameters | No | Strategy parameters to override at runtime (e.g. ALLOCATION, symbol, pct_to_trade). BotSpot saves these as an immutable strategy parameter set reusable by backtests and live bots. | |
| revisionId | No | ||
| dataProvider | No | Only for MCP clients without a BotSpot chat conversation (Claude, ChatGPT, Codex): the data source for this backtest, e.g. botspot_auto, alpaca, kalshi, polygon, or projectx. Inside BotSpot chat, use set_data_provider instead; this field is refused there. | |
| envVarSetIds | No | Saved BotSpot environment variable IDs to inject into the backtest runner. The MCP server never reads or exposes the saved values; BotSpot issues a short-lived runtime secret for the backtest. | |
| dataConnectionId | No | Saved broker connection to supply this backtest history, such as Kalshi prediction contracts, Alpaca or ProjectX futures. Credentials and account mode come from the saved connection through its private runtime lease. | |
| strategyParameterSetId | No | Existing immutable strategy parameter set for this exact saved revision. |