获取回测结果

获取回测任务的状态，以及（在结果就绪时）完整的结果。

接口

GET /v1/backtest/jobs/{id}

权重： 2

鉴权： 必需（已签名）

路径参数

名称	类型	必填	说明
id	string	是	由 创建任务 返回的任务标识符，例如 bt_3c91ef。

响应

成功响应返回完整的任务对象。result 负载仅在 status 为 done 时才会被填充。

{
  "id": "bt_3c91ef",
  "status": "done",
  "config": {
    "template_id": "tpl_grid",
    "params": {
      "grid_levels": 8,
      "upper_price": "72000",
      "lower_price": "60000"
    },
    "symbols": ["BTCUSDT"],
    "timeframe": "1h",
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-12-31T23:59:59Z",
    "capital": "10000.00",
    "leverage": 1,
    "fee_model": "fixed_bps",
    "fee_bps": "5"
  },
  "submitted_at": "2026-04-29T10:15:00Z",
  "started_at": "2026-04-29T10:15:08Z",
  "finished_at": "2026-04-29T10:17:42Z",
  "progress": 1.0,
  "result": {
    "metrics": {
      "sharpe": "1.84",
      "sortino": "2.31",
      "calmar": "1.12",
      "max_drawdown": "-0.142",
      "win_rate": "0.638",
      "profit_factor": "1.92",
      "cagr": "0.187",
      "expected_value": "12.43",
      "total_trades": 247,
      "avg_trade_duration_seconds": 14820
    },
    "equity_curve": [
      ["2025-01-01T00:00:00Z", "10000.00"],
      ["2025-01-02T00:00:00Z", "10031.50"]
    ],
    "trades": [
      {
        "id": 1,
        "side": "buy",
        "symbol": "BTCUSDT",
        "entry_time": "2025-01-15T08:00:00Z",
        "entry_price": "62100.00",
        "exit_time": "2025-01-15T14:00:00Z",
        "exit_price": "63250.00",
        "qty": "0.0805",
        "pnl": "92.58",
        "fee": "10.18"
      }
    ]
  },
  "error": null
}

任务处于 queued 或 running 时，result 为 null，progress 为 [0, 1] 的小数。任务处于 failed 时，result 为 null，error 携带失败详情。

响应字段

字段	类型	说明
id	string	任务标识符。
status	enum	queued、running、done、failed 或 cancelled。后三者为终止状态。
config	object	任务运行时的解析后配置。字段含义参见 创建任务。
submitted_at	string (ISO 8601)	任务被接受的时间。
started_at	string (ISO 8601) | null	Worker 开始处理的时间。
finished_at	string (ISO 8601) | null	任务进入终止状态的时间。
progress	number	位于 [0, 1] 的进度比例。完成时为 1.0。
result	object | null	仅在 status = "done" 时填充。
result.metrics	object	性能指标。定义参见 指标。
result.equity_curve	array<[ISO 8601, decimal string]>	权益样本；模拟周期内每天一条。
result.trades	array<object>	已平仓成交。每条成交包含 id、side、symbol、entry_time、entry_price、exit_time、exit_price、qty、pnl、fee。
error	object | null	当 status = "failed" 时为 { "code", "message" }。

轮询建议

• 单个任务每 5 秒最多轮询一次。更激进的轮询会被限流。
• 一旦 status 进入终止值（done、failed、cancelled），立即停止轮询。
• 对长时间运行的任务，建议在前几次轮询之后改用指数退避。

大结果分页

对于跨度较长的回测，result.equity_curve 与 result.trades 未来可能会分页以控制响应体积。在首发版本中，完整数组始终在一次响应中返回。

未来： 通过 ?expand=equity_curve&cursor=...（以及 expand=trades）显式选择启用分页。届时默认响应只返回指标与每个数组的首页。

错误

HTTP	错误码	原因
404	NOT_FOUND	任务 ID 不存在，或不归当前已鉴权密钥所有。

通用错误语义参见 错误。

示例

curl -X GET https://api.pipai.example/v1/backtest/jobs/bt_3c91ef \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG"