Run a backtest
run_backtestIdempotent
Submit a point-in-time backtest. NON-BLOCKING: returns a run_id at once; poll get_backtest.
`job_status` tells you where it is: `cached` (this exact backtest was already computed — the
stored result is returned immediately), `done` (it finished within `wait_seconds`), or
`queued` / `running` (call `get_backtest(run_id)` until it is `done` or `failed`). The same
spec always has the same run_id, so re-submitting is free and never computes twice.
The run may only see data stamped on or before `as_of` — that is enforced structurally, not
by convention. Results arrive with the data `query_ids` behind them and an anti-overfitting
verdict (out-of-sample, deflated Sharpe, multiple-comparison, crash stress); a run that
fails the gate is returned REJECTED with reasons rather than hidden.
Args:
strategy_id: a registered strategy, e.g. 'buy_and_hold' or 'cross_sectional_momentum'.
start / end: the測試期間 (YYYY-MM-DD). `end` must not be after `as_of`.
as_of: the knowledge cutoff. REQUIRED — there is no "today" default.
tickers: required when universe_kind='explicit'; ignored for 'point_in_time'.
universe_kind: 'point_in_time' (survivorship-safe, resolved from listing/delisting
dates at each rebalance) or 'explicit' (a list you supplied).
market: optional market filter for a point-in-time universe.
rebalance: 'daily' | 'weekly' | 'monthly' | 'quarterly'.
cost_bps: one-way transaction cost in basis points.
params: strategy parameters, e.g. {'lookback_days': 60, 'top_k': 5}.
wait_seconds: how long this call may wait for a FAST run to finish before answering
`queued`/`running` (0 = answer at once; capped at 10). It never waits for a slow run.
costs: the trading costs to simulate, e.g. {"model": "tw_default_model"} (standard:
0.1425% commission both sides + 0.3% securities tax on sells + slippage),
{"model": "tw_default_model", "fee_discount": 0.28} (a 2.8-fold broker discount on
the commission; the tax is statutory and cannot be discounted), or {"model": "none"}
(commission and tax zeroed — the result is flagged as not a real-world result).
Omit for standard. Do not combine with cost_bps. The response's `costs` says exactly
what was applied.
Strategies served by the Zipline engine are limited to a 3-year window per interactive
request (`error: "window_exceeds_interactive_cap"`, with a suggested window). Full-period
results for the strategy-library strategies are precomputed nightly on the marketplace.
This measures history. It is not advice and it places no orders.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ||
| as_of | Yes | ||
| costs | No | ||
| label | No | ||
| start | Yes | ||
| market | No | ||
| params | No | ||
| tickers | No | ||
| cost_bps | No | ||
| rebalance | No | monthly | |
| strategy_id | Yes | ||
| wait_seconds | No | ||
| universe_kind | No | point_in_time |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cagr | No | ||
| hint | No | ||
| spec | No | ||
| as_of | No | ||
| costs | No | ||
| error | No | ||
| fills | No | ||
| queue | No | ||
| engine | No | ||
| period | No | ||
| reason | No | ||
| run_id | No | ||
| sharpe | No | ||
| status | No | ||
| trades | No | ||
| blocked | No | ||
| metrics | No | ||
| accepted | No | ||
| turnover | No | ||
| warnings | No | ||
| cache_hit | No | ||
| citations | No | ||
| data_gaps | No | ||
| poll_with | No | ||
| query_ids | No | ||
| job_status | No | ||
| lot_method | No | ||
| gate_passed | No | ||
| trade_count | No | ||
| bundle_trust | No | ||
| equity_curve | No | ||
| max_drawdown | No | ||
| bundle_version | No | ||
| engine_version | No | ||
| queue_position | No | ||
| interactive_cap | No | ||
| running_seconds | No | ||
| anti_overfitting | No | ||
| estimate_seconds | No | ||
| known_strategies | No | ||
| marketplace_card | No | ||
| equity_curve_base | No | ||
| persistence_error | No | ||
| rejection_reasons | No | ||
| run_id_resolvable | No | ||
| survivorship_safe | No | ||
| citations_persisted | No | ||
| trade_detail_reason | No | ||
| trade_detail_status | No | ||
| not_investment_advice | No | ||
| trade_detail_persisted | No |