Backtest API

The Backtest API powers the Sequency rule-driven backtester, enabling R&D engineers to stress-test intraday signal strategies against historical market data, optimize parameters, and analyze edge quality. This group includes two versions: the original /v1 (fixed-request, blocking) and the modern /v2 (async, Redis-driven, out-of-process workers). Base path: /api/graph/v1/backtest Auth: Public routes require a Supabase JWT (user) OR an X-Internal-Secret header (service principal). Strict auth is enforced in production (anon → 401).

Core Backtest Run (v1)

POST /api/graph/v1/backtest

Start a backtest run Launches a historical backtest of intraday signal strategies. The request registers a pending run and spawns a background task to execute it (no longer blocks the HTTP call). Poll GET /{run_id} for results. Parameters: None (all config in request body) Request body:

{
  "symbols": ["NVDA", "AAPL"],
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "signal_types": ["vwap_touch", "ib_breakout"],
  "stop_atr_mult": 1.5,
  "t1_atr_mult": 2.0,
  "t2_atr_mult": 3.0,
  "t3_atr_mult": 4.0,
  "time_stop_et": "15:45",
  "position_size": 100,
  "slippage_per_share": 0.01,
  "commission_per_share": 0.001,
  "gate_thresholds": null
}

Response 200:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "symbols": ["NVDA", "AAPL"],
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "signal_types": ["vwap_touch", "ib_breakout"],
  "stop_atr_mult": 1.5,
  "t1_atr_mult": 2.0,
  "t2_atr_mult": 3.0,
  "t3_atr_mult": 4.0,
  "time_stop_et": "15:45",
  "created_at": "2024-01-15T10:30:00Z",
  "position_size": 100,
  "slippage_per_share": 0.01,
  "commission_per_share": 0.001
}

Constraints:

Max 50 symbols per run
Max 365-day date range
Max 3 concurrent pending/running backtests per user (returns 429 if exceeded)
end_date must be after start_date

GET /api/graph/v1/backtest/

Get backtest run status Poll the status and full results of a backtest run. Returns the same shape as the response above, plus computed metrics once the run completes. Parameters:

run_id (path, required): UUID of the backtest run

Response 200:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "symbols": ["NVDA"],
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "signal_types": ["vwap_touch"],
  "stop_atr_mult": 1.5,
  "t1_atr_mult": 2.0,
  "t2_atr_mult": 3.0,
  "t3_atr_mult": 4.0,
  "time_stop_et": "15:45",
  "total_trades": 42,
  "win_count": 28,
  "loss_count": 14,
  "win_rate": 0.667,
  "avg_rr_ratio": 1.85,
  "total_pnl": 12450.50,
  "max_drawdown": -0.08,
  "profit_factor": 2.15,
  "sharpe_ratio": 1.42,
  "by_signal_type": [
    {
      "signal_type": "vwap_touch",
      "total_trades": 42,
      "win_count": 28,
      "loss_count": 14,
      "win_rate": 0.667,
      "avg_pnl_r": 0.85,
      "expectancy_per_r": 1.15,
      "total_pnl": 12450.50
    }
  ],
  "by_symbol": [
    {
      "symbol": "NVDA",
      "total_trades": 42,
      "win_count": 28,
      "loss_count": 14,
      "win_rate": 0.667,
      "total_pnl": 12450.50,
      "max_drawdown": -0.08
    }
  ],
  "equity_curve": [
    {"trade_num": 1, "cumulative_pnl": 245.25, "cumulative_r": 0.5},
    {"trade_num": 2, "cumulative_pnl": 980.75, "cumulative_r": 2.0}
  ],
  "validation_gate": {
    "passed": true,
    "criteria": [
      {
        "name": "Sample Size",
        "description": "Minimum 30 trades for statistical significance",
        "threshold": "≥ 30",
        "actual": "42",
        "passed": true
      },
      {
        "name": "Profit Factor",
        "description": "Total profits must exceed total losses",
        "threshold": "≥ 1.00",
        "actual": "2.15",
        "passed": true
      }
    ]
  },
  "progress_pct": 100,
  "started_at": "2024-01-15T10:31:00Z",
  "completed_at": "2024-01-15T10:45:00Z",
  "created_at": "2024-01-15T10:30:00Z",
  "position_size": 100,
  "slippage_per_share": 0.01,
  "commission_per_share": 0.001
}

Status lifecycle: pending → running → completed | failed | cancelled

GET /api/graph/v1/backtest//trades

Get backtest trades (paginated) Retrieve individual trades from a completed backtest run with optional filtering by symbol, signal type, or direction. Parameters:

run_id (path, required): UUID of the backtest run
page (query, optional): Page number (default 1, min 1)
page_size (query, optional): Trades per page (default 50, max 200)
symbol (query, optional): Filter by symbol (e.g., “NVDA”)
signal_type (query, optional): Filter by signal type
direction (query, optional): Filter by direction (“long” | “short”)

Response 200:

{
  "trades": [
    {
      "entry_time": "2024-01-15T09:45:00Z",
      "symbol": "NVDA",
      "signal_type": "vwap_touch",
      "direction": "long",
      "trigger_price": 845.50,
      "entry_price": 846.00,
      "exit_price": 855.25,
      "stop_price": 840.00,
      "t1_price": 851.00,
      "t2_price": 856.00,
      "t3_price": 861.00,
      "atr_at_entry": 3.50,
      "exit_reason": "t1_hit",
      "pnl": 370.25,
      "pnl_r": 2.57,
      "round_trip_cost": 8.50,
      "hold_minutes": 45,
      "exit_time": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 50
}

GET /api/graph/v1/backtest//trades/export

Export backtest trades Export all trades from a run as CSV or JSON. Parameters:

run_id (path, required): UUID of the backtest run
format (query, optional): "csv" or "json" (default “csv”)

Response 200: File download (CSV or JSON array)

POST /api/graph/v1/backtest//cancel

Cancel a backtest run Cancel a running or pending backtest. Returns 409 if the run is already completed or failed. Parameters:

run_id (path, required): UUID of the backtest run

Response 200:

{
  "status": "cancelled",
  "run_id": "550e8400-e29b-41d4-a716-446655440000"
}

POST /api/graph/v1/backtest//analyze

AI analysis of backtest results Run LLM analysis on a completed backtest to assess edge quality, signal insights, and risk factors. Parameters:

run_id (path, required): UUID of the backtest run

Response 200:

{
  "summary": "The strategy shows solid statistical edge with a 2.15 profit factor across 42 trades...",
  "signal_insights": [
    {
      "signal_type": "vwap_touch",
      "assessment": "Strong signal quality with 66.7% win rate",
      "reasoning": "VWAP reverts reliably in low-volatility regimes",
      "suggestion": "Consider increasing position size on VWAP touches in the first 30 minutes"
    }
  ],
  "risk_assessment": "Drawdown remains within 8% on a $100k account; consider adding regime filters for volatile market days",
  "parameter_suggestions": [
    "Increase stop_atr_mult from 1.5 to 2.0 for higher reward-to-risk",
    "Add time_stop filter for post-3pm trades (lower volume)"
  ],
  "edge_quality": "Medium-High",
  "edge_confidence": 0.78,
  "analyzed_at": "2024-01-15T10:46:00Z",
  "tokens_used": 2450
}

History & Optimization (v1)

GET /api/graph/v1/backtest/history

List backtest history Retrieve the user’s past backtest runs (most recent first). Parameters:

limit (query, optional): Max results (default 50, max 100)

Response 200: Array of BacktestRunResponse objects (see GET /{run_id} for structure)

POST /api/graph/v1/backtest/optimize

Start parameter optimization Run a grid search over stop/target ATR multiplier combinations to find optimal parameters. Request body:

{
  "symbols": ["NVDA"],
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "signal_types": ["vwap_touch"],
  "stop_atr_range": [1.0, 1.5, 2.0],
  "target_atr_range": [2.0, 2.5, 3.0],
  "top_n": 5
}

Response 200:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "results": null,
  "progress_pct": 0,
  "error_message": null
}

Poll the id returned by calling GET /api/graph/v1/backtest/{run_id} to retrieve results as they complete.

GET /api/graph/v1/backtest/field-availability

Per-field coverage for rule-driven backtester Reports which scoring/indicator/regime fields are populated in backtest_universe for a given date range, so the Visual Canvas can render honest “available from” badges and block rules that depend on fields with insufficient coverage. Parameters:

from (query, required): YYYY-MM-DD (inclusive)
to (query, required): YYYY-MM-DD (inclusive)
symbols (query, optional): Comma-separated filter. Omit for universe-wide coverage (fastest). Provide the same symbols you intend to backtest for accuracy.

Response 200:

{
  "from": "2024-01-01",
  "to": "2024-12-31",
  "symbols": ["NVDA"],
  "fields": {
    "rsi_14": {
      "status": "available",
      "coverage_pct": 99.5,
      "category": "indicator",
      "available_from": "2022-01-01"
    },
    "regime_grid": {
      "status": "available",
      "coverage_pct": 100.0,
      "category": "regime",
      "available_from": "2020-01-01"
    },
    "vp_poc": {
      "status": "partial",
      "coverage_pct": 45.0,
      "category": "level",
      "available_from": "2024-06-01"
    },
    "vp_poc_options": {
      "status": "forward_only",
      "coverage_pct": 0.0,
      "category": "level",
      "available_from": null
    }
  }
}

Status values:

available: ≥90% coverage; rules can run with confidence
partial: ≥10% coverage; rules run but results exclude uncovered bars
missing: <10% coverage; rules are effectively inoperable
forward_only: field only exists in live score_history, never in historical backtest_universe

Modern Async Backtest (v2)

The /v2 endpoints use ClickHouse-backed async execution with out-of-process workers, supporting advanced features like walk-forward analysis, Monte Carlo simulation, regime fitness, and detailed equity-curve metrics.

POST /api/graph/v1/backtest/v2/run

Start async backtest run (v2) Launches a modern async backtest with advanced parameters. Returns immediately with status pending; poll GET /run/{run_id} for progress. Request body:

{
  "symbols": ["NVDA", "AAPL"],
  "signal_types": ["vwap_touch", "ib_breakout"],
  "quality_tiers": ["EXCELLENT", "GOOD"],
  "regime_filter": ["BULL_HIGH_VOL", "NEUTRAL_LOW_VOL"],
  "date_from": "2024-01-01",
  "date_to": "2024-12-31",
  "stop_atr": 1.5,
  "target_atr": 2.5,
  "time_stop": "15:45",
  "slippage_model": "realistic",
  "fee_model": "commission_per_share",
  "initial_capital": 100000.0,
  "max_positions": 5,
  "sizing_method": "score_weighted",
  "strategy_rules": null,
  "universe_symbols": null,
  "benchmark_symbol": "SPY",
  "bar_timeframe": "1min",
  "timeframe": "intraday",
  "train_test_split": 0.8,
  "walk_forward": true,
  "monte_carlo_n": 10000,
  "random_seed": 42,
  "regime_strategy": null
}

Response 200:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "progress_pct": 0
}

Constraints:

Max 3 concurrent runs per user (returns 429)
Max 365-day range
sizing_method: equal_weight, score_weighted, risk_parity, or kelly
Max 50 symbols
mse_signal conditions not yet supported (use indicator/price-action/pattern/volume instead)

GET /api/graph/v1/backtest/v2/run/

Get run status (v2) Poll the status and progress of a v2 backtest run. Parameters:

run_id (path, required): Run UUID

Response 200:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress_pct": 45,
  "total_trades": 0,
  "phase": "analyzing_trades",
  "total_signals": 250,
  "symbols_processed": 2,
  "symbols_total": 5,
  "current_symbol": "AAPL",
  "request_config": {
    "date_from": "2024-01-01",
    "date_to": "2024-12-31",
    "stop_atr": 1.5
  }
}

GET /api/graph/v1/backtest/v2/run//results

Get full backtest results (v2) Retrieve complete results including trades, portfolio metrics, equity curve, Monte Carlo analysis, and validation gate. Parameters:

run_id (path, required): Run UUID

Response 200:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_trades": 42,
  "metrics": {
    "win_rate": 0.667,
    "profit_factor": 2.15,
    "sharpe_ratio": 1.42,
    "sortino_ratio": 1.65,
    "max_drawdown_pct": -8.0,
    "expectancy_pct": 2.85,
    "avg_winner_pct": 1.45,
    "avg_loser_pct": -0.85
  },
  "benchmark_metrics": {
    "beta": 1.15,
    "correlation": 0.78,
    "alpha": 0.025,
    "excess_return_pct": 18.5
  },
  "benchmark_alpha": {
    "alpha_pct": 2.5,
    "tracking_error": 5.2,
    "information_ratio": 0.48
  },
  "detailed_metrics": {
    "by_signal_type": [
      {
        "signal_type": "vwap_touch",
        "trades": 28,
        "win_rate": 0.75,
        "profit_factor": 2.4,
        "expectancy_pct": 3.2
      }
    ],
    "by_regime": [
      {
        "regime": "BULL_HIGH_VOL",
        "trades": 15,
        "win_rate": 0.8,
        "profit_factor": 2.8
      }
    ],
    "by_quality_tier": [
      {
        "tier": "EXCELLENT",
        "trades": 30,
        "win_rate": 0.7,
        "profit_factor": 2.3
      }
    ],
    "by_symbol": [
      {
        "symbol": "NVDA",
        "trades": 22,
        "win_rate": 0.68,
        "profit_factor": 2.1
      }
    ]
  },
  "monte_carlo": {
    "final_equity_ci_low": 108500.0,
    "final_equity_ci_high": 116200.0,
    "ruin_probability_pct": 0.1,
    "worst_case_drawdown_pct": -18.5,
    "best_case_final_equity": 125000.0
  },
  "equity_curve_metrics": {
    "cagr_pct": 12.5,
    "total_return_pct": 18.2,
    "sharpe_ratio": 1.42,
    "sortino_ratio": 1.65,
    "max_drawdown_pct": -8.0,
    "calmar_ratio": 1.56,
    "n_days": 252,
    "densified": true,
    "n_sessions": 250
  },
  "breadth": {
    "n_symbols": 5,
    "n_trades": 42,
    "net_pnl_dollars": 18200.0,
    "top1_pnl_share_pct": 35.0,
    "top3_pnl_share_pct": 65.0,
    "net_pnl_ex_top3_dollars": 6370.0,
    "pct_symbols_profitable": 80.0,
    "herfindahl": 0.28,
    "is_single_name_artifact": false
  },
  "validation_gate": {
    "passed": true,
    "criteria": [
      {
        "name": "Sample Size",
        "threshold": "≥ 30",
        "actual": "42",
        "passed": true
      },
      {
        "name": "Profit Factor",
        "threshold": "≥ 1.00",
        "actual": "2.15",
        "passed": true
      },
      {
        "name": "Sharpe Ratio",
        "threshold": "≥ 0.50",
        "actual": "1.42",
        "passed": true
      },
      {
        "name": "Max Drawdown",
        "threshold": "≤ 25%",
        "actual": "8.0%",
        "passed": true
      },
      {
        "name": "Win Rate",
        "threshold": "≥ 35%",
        "actual": "66.7%",
        "passed": true
      }
    ]
  },
  "trades": [
    {
      "symbol": "NVDA",
      "direction": "long",
      "signal_type": "vwap_touch",
      "quality_tier": "EXCELLENT",
      "entry_timestamp": "2024-01-15T09:45:00Z",
      "entry_price": 846.00,
      "exit_timestamp": "2024-01-15T10:30:00Z",
      "exit_price": 855.25,
      "exit_reason": "t1_hit",
      "holding_period_minutes": 45,
      "pnl_pct": 1.09,
      "pnl_r_multiple": 2.57,
      "pnl_dollars": 370.25,
      "sizing_multiplier": 1.0,
      "conviction_at_entry": 85,
      "regime_dominant": "BULL_HIGH_VOL",
      "slippage_model": "realistic",
      "entry_slippage_bps": 2.5,
      "exit_slippage_bps": 2.5,
      "total_slippage_bps": 5.0,
      "entry_atr": 3.50,
      "stop_price": 840.00,
      "target_price": 851.00,
      "stop_atr_multiplier": 1.5,
      "target_atr_multiplier": 2.5,
      "signal_details": {
        "vwap_deviation_pct": -0.8,
        "volume_profile_tier": "HIGH_VOLUME_NODE"
      },
      "mfe_30min": 1.5,
      "mae_30min": -0.3,
      "mfe_eod": 2.1,
      "mae_eod": -0.5
    }
  ],
  "equity_curve": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "equity": 100370.25,
      "drawdown": 0.0,
      "position_count": 1
    }
  ],
  "walk_forward_by_regime": {
    "BULL_HIGH_VOL": {
      "train_sharpe": 1.8,
      "test_sharpe": 1.2,
      "train_profit_factor": 2.8,
      "test_profit_factor": 1.9
    }
  },
  "decision_summary": {
    "entry_triggered": 250,
    "entry_filtered": 200,
    "position_opened": 42,
    "exited_t1": 25,
    "exited_stop": 5,
    "exited_time_stop": 12
  },
  "diagnostics": {
    "condition_funnel": [
      {
        "condition": "signal_triggered",
        "count": 250,
        "pct": 100.0
      },
      {
        "condition": "confluence_score",
        "count": 180,
        "pct": 72.0
      },
      {
        "condition": "regime_filter",
        "count": 42,
        "pct": 16.8
      }
    ]
  },
  "execution_assumptions": {
    "timeframe": "intraday",
    "slippage_model": "realistic",
    "slippage_entry_pct": 0.025,
    "slippage_exit_pct": 0.025,
    "commission_per_trade": 2.0
  },
  "data_quality": {
    "split_adjustments_applied": 3,
    "trade_count": 42,
    "coverage": {
      "symbol_coverage_pct": 98.5,
      "bar_completeness_pct": 99.2
    }
  },
  "request_config": {
    "date_from": "2024-01-01",
    "date_to": "2024-12-31",
    "symbols": ["NVDA", "AAPL"],
    "signal_types": ["vwap_touch", "ib_breakout"],
    "stop_atr": 1.5,
    "target_atr": 2.5
  }
}

Returns 202 with progress info while the run is still in progress. When a backtest produces fewer than 5 trades, includes a diagnostics field showing the condition funnel.

GET /api/graph/v1/backtest/v2/run//results/by-symbol

Get per-symbol attribution (v2) Breakdown of metrics by symbol. Parameters:

run_id (path, required): Run UUID

Response 200: Array of per-symbol metrics (trades, win_rate, profit_factor, sharpe, max_drawdown)

GET /api/graph/v1/backtest/v2/run//results/regime-fitness

Get regime fitness breakdown (v2) Performance across different market regimes (2×3 grid: BULL/NEUTRAL/BEAR × LOW_VOL/HIGH_VOL). Parameters:

run_id (path, required): Run UUID

Response 200: Metrics grouped by regime

GET /api/graph/v1/backtest/v2/run//trades/

Get single trade detail (v2) Retrieve enriched data for a specific trade, including stop/target levels for chart visualization. Parameters:

run_id (path, required): Run UUID
trade_index (path, required): Trade index (0-based)

Response 200:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "trade_index": 0,
  "symbol": "NVDA",
  "direction": "long",
  "signal_type": "vwap_touch",
  "quality_tier": "EXCELLENT",
  "entry_timestamp": "2024-01-15T09:45:00Z",
  "entry_price": 846.00,
  "exit_timestamp": "2024-01-15T10:30:00Z",
  "exit_price": 855.25,
  "exit_reason": "t1_hit",
  "holding_period_minutes": 45,
  "pnl_pct": 1.09,
  "pnl_r_multiple": 2.57,
  "pnl_dollars": 370.25,
  "sizing_multiplier": 1.0,
  "conviction_at_entry": 85,
  "regime_dominant": "BULL_HIGH_VOL",
  "slippage_model": "realistic",
  "entry_slippage_bps": 2.5,
  "exit_slippage_bps": 2.5,
  "total_slippage_bps": 5.0,
  "entry_atr": 3.50,
  "stop_price": 840.00,
  "target_price": 851.00,
  "stop_atr_multiplier": 1.5,
  "target_atr_multiplier": 2.5,
  "signal_details": {
    "vwap_deviation_pct": -0.8,
    "volume_profile_tier": "HIGH_VOLUME_NODE"
  }
}

POST /api/graph/v1/backtest/v2/run//cancel

Cancel backtest run (v2) Parameters:

run_id (path, required): Run UUID

Response 200:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled"
}

Annotations (v2)

PUT /api/graph/v1/backtest/v2/run//trades//annotate

Annotate a trade Add tags and notes to a trade for later reference. Parameters:

run_id (path, required): Run UUID
trade_id (path, required): Trade UUID

Request body:

{
  "tags": ["winner", "low_volume"],
  "note": "Perfect entry at VWAP, exited at first target"
}

Response 200: Annotation created

DELETE /api/graph/v1/backtest/v2/run//trades//annotate

Delete annotation Remove annotations from a trade. Parameters:

run_id (path, required): Run UUID
trade_id (path, required): Trade UUID

Response 200: Annotation deleted

GET /api/graph/v1/backtest/v2/run//annotations

Get run annotations List all annotations for trades in a backtest run. Parameters:

run_id (path, required): Run UUID

Response 200: Array of annotations

GET /api/graph/v1/backtest/v2/annotations

Search annotations Search annotations across all backtest runs by tag. Parameters:

tag (query, optional): Filter by tag
limit (query, optional): Max results

Response 200: Array of annotations

History & Groups (v2)

GET /api/graph/v1/backtest/v2/runs

List runs (v2) Paginated list of the user’s backtest runs. Parameters:

limit (query, optional): Max results (default 50)
offset (query, optional): Pagination offset

Response 200: Array of run summaries

GET /api/graph/v1/backtest/v2/history

Backtest history with filters Paginated history with optional signal type filter. Parameters:

signal_type (query, optional): Filter by signal type
limit (query, optional): Max results
offset (query, optional): Pagination offset

Response 200: Array of run objects

POST /api/graph/v1/backtest/v2/groups

Create symbol group Create a named group of symbols for reuse across backtests. Request body:

{
  "group_name": "Tech Mega Caps",
  "symbols": ["NVDA", "AAPL", "MSFT", "GOOGL"]
}

Response 200: Group created

GET /api/graph/v1/backtest/v2/groups

List groups Retrieve all symbol groups for the user. Response 200: Array of groups

PUT /api/graph/v1/backtest/v2/groups/

Update group Modify a symbol group’s name or member list. Parameters:

group_id (path, required): Group UUID

Request body: Same as POST /groups Response 200: Group updated

DELETE /api/graph/v1/backtest/v2/groups/

Delete group Remove a symbol group. Parameters:

group_id (path, required): Group UUID

Response 200: Group deleted

Parameter Optimization (v2)

POST /api/graph/v1/backtest/v2/optimize

Optimize parameters (v2) Run walk-forward parameter optimization to find best stop/target ATR combinations. Request body:

{
  "materialize_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "signal_types": ["vwap_touch"],
  "quality_tiers": ["EXCELLENT", "GOOD"],
  "date_from": "2024-01-01",
  "date_to": "2024-12-31",
  "objective": "sharpe",
  "walk_forward": true,
  "n_folds": 5
}

Response 200:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "results": null,
  "progress_pct": 0
}

POST /api/graph/v1/backtest/v2/sweep

Parameter sensitivity sweep (async) Run a parameter sweep and retrieve results asynchronously. Request body:

{
  "base_request": {
    "symbols": ["NVDA"],
    "date_from": "2024-01-01",
    "date_to": "2024-12-31"
  },
  "param_ranges": [
    {"stop_atr": [1.0, 1.5, 2.0]},
    {"target_atr": [2.0, 2.5, 3.0]}
  ],
  "target_metric": "sharpe"
}

Response 200:

{
  "sweep_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "progress_pct": 0
}

GET /api/graph/v1/backtest/v2/sweep//status

Sweep progress Poll the status of an async parameter sweep. Parameters:

sweep_id (path, required): Sweep UUID

Response 200:

{
  "sweep_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress_pct": 35,
  "total_combinations": 9,
  "completed": 3
}

GET /api/graph/v1/backtest/v2/sweep//results

Sweep results matrix Retrieve the results matrix after a sweep completes. Parameters:

sweep_id (path, required): Sweep UUID

Response 200: Parameter combinations with metrics (Sharpe, profit_factor, win_rate, etc.)

Comparison & Analysis (v2)

Endpoint	Purpose
`POST /api/graph/v1/backtest/v2/compare`	Compare 2-5 backtest runs side-by-side
`POST /api/graph/v1/backtest/v2/compare/detailed`	Compare with trade deltas and overlap analysis
`GET /api/graph/v1/backtest/v2/progression`	Tier progression dashboard
`GET /api/graph/v1/backtest/v2/coverage`	Backtest data coverage summary
`GET /api/graph/v1/backtest/v2/universe/status`	Universe status and field availability

Strategies & Forward Testing (v2)

Endpoint	Purpose
`POST /api/graph/v1/backtest/v2/strategies/versions`	Save strategy version
`GET /api/graph/v1/backtest/v2/strategies/{strategy_name}/versions`	List strategy versions
`GET /api/graph/v1/backtest/v2/strategies/versions/{version_id}`	Get single version
`GET /api/graph/v1/backtest/v2/strategies/versions/{v1}/diff/{v2}`	Diff two versions
`GET /api/graph/v1/backtest/v2/strategies/versions/{v1}/signal-overlap/{v2}`	Signal overlap analysis
`POST /api/graph/v1/backtest/v2/strategy-test`	Simplified retail backtest (see Schemas below)
`POST /api/graph/v1/backtest/v2/forward-test`	Start paper trading session
`GET /api/graph/v1/backtest/v2/forward-test/{session_id}`	Session status
`POST /api/graph/v1/backtest/v2/forward-test/{session_id}/stop`	Stop session
`GET /api/graph/v1/backtest/v2/forward-test/{session_id}/fills`	Session fills
`GET /api/graph/v1/backtest/v2/forward-tests`	List user’s sessions

Options Backtesting

POST /api/graph/v1/backtest/v2/options/run

Options backtest (single-leg) Backtest options strategies with delta targeting, DTE ranges, and contract selection logic. Request body:

{
  "symbols": ["NVDA"],
  "signal_types": ["vwap_touch"],
  "date_from": "2024-01-01",
  "date_to": "2024-12-31",
  "target_delta": 0.30,
  "delta_tolerance": 0.05,
  "dte_min": 7,
  "dte_max": 45,
  "min_open_interest": 100,
  "max_spread_pct": 1.0,
  "max_quote_age_seconds": 60,
  "premium_stop_pct": -20.0,
  "premium_target_pct": 50.0,
  "contracts": 1,
  "base_capital_per_trade": 10000.0,
  "commission_per_contract": 0.65
}

Response 200: Backtest results (same structure as equity backtest, with options-specific fields like delta, theta, vega decay)

Regime & Coverage

GET /api/graph/v1/backtest/v2/regime/calendar

Get regime calendar Retrieve the 2×3 regime grid labels for a date range. Parameters:

date_from (query, required): YYYY-MM-DD
date_to (query, required): YYYY-MM-DD

Response 200:

{
  "regime_calendar": [
    {
      "date": "2024-01-15",
      "regime": "BULL_HIGH_VOL",
      "vix_close": 18.5,
      "spy_close": 481.25
    }
  ]
}

POST /api/graph/v1/backtest/v2/regime/backfill

Trigger regime backfill Manually trigger a backfill of the 2×3 regime grid for a date range (normally automatic). Parameters:

date_from (query, optional): YYYY-MM-DD
date_to (query, optional): YYYY-MM-DD

Response 200: Backfill initiated

GET /api/graph/v1/backtest/v2/coverage

Get backtest coverage Return available data coverage (earliest/latest dates, symbol count) for the date picker. Response 200:

{
  "earliest": "2020-01-01",
  "latest": "2024-12-29",
  "symbol_count": 3450
}

Key Schemas

BacktestRequest

Request to launch a v1 backtest run.

{
  "symbols": [string],
  "start_date": "YYYY-MM-DD",
  "end_date": "YYYY-MM-DD",
  "signal_types": ["vwap_touch", "ib_breakout", "ib_retest", "or_hold", "level_confluence", "trend_continuation"],
  "stop_atr_mult": number,
  "t1_atr_mult": number,
  "t2_atr_mult": number,
  "t3_atr_mult": number,
  "time_stop_et": "HH:MM",
  "position_size": integer,
  "slippage_per_share": number,
  "commission_per_share": number,
  "gate_thresholds": object | null
}

BacktestRunRequest

Request to launch a v2 backtest run (see above for full structure).

BacktestTradeResponse

Individual trade from a backtest result.

{
  "entry_time": "ISO 8601 timestamp",
  "symbol": "NVDA",
  "signal_type": "vwap_touch",
  "direction": "long" | "short",
  "trigger_price": number,
  "entry_price": number,
  "exit_price": number | null,
  "stop_price": number,
  "t1_price": number | null,
  "t2_price": number | null,
  "t3_price": number | null,
  "atr_at_entry": number,
  "exit_reason": "t1_hit" | "t2_hit" | "t3_hit" | "stop_hit" | "time_stop" | "eod",
  "pnl": number,
  "pnl_r": number,
  "round_trip_cost": number,
  "hold_minutes": integer | null,
  "exit_time": "ISO 8601 timestamp" | null
}

SignalType

Intraday signal types available for backtesting.

enum: "vwap_touch" | "ib_breakout" | "ib_retest" | "or_hold" | "level_confluence" | "trend_continuation"

BacktestStatus

Run lifecycle status.

enum: "pending" | "running" | "completed" | "failed" | "cancelled"

EquityCurvePoint

Single point on the equity curve (cumulative P&L by trade count and R-multiple).

{
  "trade_num": integer,
  "cumulative_pnl": number,
  "cumulative_r": number,
  "timestamp": "ISO 8601 timestamp" | null
}

ValidationGateResult

Aggregate validation gate (P3 Phase 3: sample size, profit factor, Sharpe, max drawdown, win rate).

{
  "passed": boolean,
  "criteria": [
    {
      "name": "Sample Size",
      "description": "Minimum 30 trades for statistical significance",
      "threshold": "≥ 30",
      "actual": "42",
      "passed": boolean
    }
  ]
}

TradeDetailResponse

Enriched single-trade response with stop/target levels and detailed signal metadata.

{
  "run_id": "UUID",
  "trade_index": integer,
  "symbol": "NVDA",
  "direction": "long" | "short",
  "signal_type": "vwap_touch",
  "quality_tier": "EXCELLENT" | "GOOD" | "MARGINAL" | "POOR",
  "entry_timestamp": "ISO 8601",
  "entry_price": number,
  "exit_timestamp": "ISO 8601",
  "exit_price": number,
  "exit_reason": "t1_hit" | "stop_hit" | "time_stop",
  "holding_period_minutes": integer,
  "pnl_pct": number,
  "pnl_r_multiple": number,
  "pnl_dollars": number,
  "sizing_multiplier": number,
  "conviction_at_entry": number (0–100),
  "regime_dominant": "BULL_HIGH_VOL" | "BULL_LOW_VOL" | "NEUTRAL_HIGH_VOL" | "NEUTRAL_LOW_VOL" | "BEAR_HIGH_VOL" | "BEAR_LOW_VOL",
  "slippage_model": "realistic" | "pessimistic",
  "entry_slippage_bps": number,
  "exit_slippage_bps": number,
  "total_slippage_bps": number,
  "entry_atr": number,
  "stop_price": number | null,
  "target_price": number | null,
  "stop_atr_multiplier": number,
  "target_atr_multiplier": number,
  "signal_details": object
}

StrategyTestRequest

Simplified retail backtest request.

{
  "signal_types": [string],
  "quality_tiers": ["EXCELLENT", "GOOD"],
  "date_from": "YYYY-MM-DD",
  "date_to": "YYYY-MM-DD",
  "stop_atr": number,
  "target_atr": number
}

PromoteFromBacktestRequest

Promote a strategy (post-backtest) to a Trade Manager card.

{
  "symbol": "NVDA",
  "mode": "autonomous" | "supervised" | "monitor" | "manual",
  "paper_live_mode": "paper" | "live",
  "sizing_type": "fixed_pct" | "kelly",
  "sizing_value": number
}

​Backtest API

​Core Backtest Run (v1)

​POST /api/graph/v1/backtest

​GET /api/graph/v1/backtest/

​GET /api/graph/v1/backtest//trades

​GET /api/graph/v1/backtest//trades/export

​POST /api/graph/v1/backtest//cancel

​POST /api/graph/v1/backtest//analyze

​History & Optimization (v1)

​GET /api/graph/v1/backtest/history

​POST /api/graph/v1/backtest/optimize

​GET /api/graph/v1/backtest/field-availability

​Modern Async Backtest (v2)

​POST /api/graph/v1/backtest/v2/run

​GET /api/graph/v1/backtest/v2/run/

​GET /api/graph/v1/backtest/v2/run//results

​GET /api/graph/v1/backtest/v2/run//results/by-symbol

​GET /api/graph/v1/backtest/v2/run//results/regime-fitness

​GET /api/graph/v1/backtest/v2/run//trades/

​POST /api/graph/v1/backtest/v2/run//cancel

​Annotations (v2)

​PUT /api/graph/v1/backtest/v2/run//trades//annotate

​DELETE /api/graph/v1/backtest/v2/run//trades//annotate

​GET /api/graph/v1/backtest/v2/run//annotations

​GET /api/graph/v1/backtest/v2/annotations

​History & Groups (v2)

​GET /api/graph/v1/backtest/v2/runs

​GET /api/graph/v1/backtest/v2/history

​POST /api/graph/v1/backtest/v2/groups

​GET /api/graph/v1/backtest/v2/groups

​PUT /api/graph/v1/backtest/v2/groups/

​DELETE /api/graph/v1/backtest/v2/groups/

​Parameter Optimization (v2)

​POST /api/graph/v1/backtest/v2/optimize

​POST /api/graph/v1/backtest/v2/sweep

​GET /api/graph/v1/backtest/v2/sweep//status

​GET /api/graph/v1/backtest/v2/sweep//results

​Comparison & Analysis (v2)

​Strategies & Forward Testing (v2)

​Options Backtesting

​POST /api/graph/v1/backtest/v2/options/run

​Regime & Coverage

​GET /api/graph/v1/backtest/v2/regime/calendar

​POST /api/graph/v1/backtest/v2/regime/backfill

​GET /api/graph/v1/backtest/v2/coverage

​Key Schemas

​BacktestRequest

​BacktestRunRequest

​BacktestTradeResponse

​SignalType

​BacktestStatus

​EquityCurvePoint

​ValidationGateResult

​TradeDetailResponse

​StrategyTestRequest

​PromoteFromBacktestRequest

Backtest API

Core Backtest Run (v1)

POST /api/graph/v1/backtest

GET /api/graph/v1/backtest/

GET /api/graph/v1/backtest//trades

GET /api/graph/v1/backtest//trades/export

POST /api/graph/v1/backtest//cancel

POST /api/graph/v1/backtest//analyze

History & Optimization (v1)

GET /api/graph/v1/backtest/history

POST /api/graph/v1/backtest/optimize

GET /api/graph/v1/backtest/field-availability

Modern Async Backtest (v2)

POST /api/graph/v1/backtest/v2/run

GET /api/graph/v1/backtest/v2/run/

GET /api/graph/v1/backtest/v2/run//results

GET /api/graph/v1/backtest/v2/run//results/by-symbol

GET /api/graph/v1/backtest/v2/run//results/regime-fitness

GET /api/graph/v1/backtest/v2/run//trades/

POST /api/graph/v1/backtest/v2/run//cancel

Annotations (v2)

PUT /api/graph/v1/backtest/v2/run//trades//annotate

DELETE /api/graph/v1/backtest/v2/run//trades//annotate

GET /api/graph/v1/backtest/v2/run//annotations

GET /api/graph/v1/backtest/v2/annotations

History & Groups (v2)

GET /api/graph/v1/backtest/v2/runs

GET /api/graph/v1/backtest/v2/history

POST /api/graph/v1/backtest/v2/groups

GET /api/graph/v1/backtest/v2/groups

PUT /api/graph/v1/backtest/v2/groups/

DELETE /api/graph/v1/backtest/v2/groups/

Parameter Optimization (v2)

POST /api/graph/v1/backtest/v2/optimize

POST /api/graph/v1/backtest/v2/sweep

GET /api/graph/v1/backtest/v2/sweep//status

GET /api/graph/v1/backtest/v2/sweep//results

Comparison & Analysis (v2)

Strategies & Forward Testing (v2)

Options Backtesting

POST /api/graph/v1/backtest/v2/options/run

Regime & Coverage

GET /api/graph/v1/backtest/v2/regime/calendar

POST /api/graph/v1/backtest/v2/regime/backfill

GET /api/graph/v1/backtest/v2/coverage

Key Schemas

BacktestRequest

BacktestRunRequest

BacktestTradeResponse

SignalType

BacktestStatus

EquityCurvePoint

ValidationGateResult

TradeDetailResponse

StrategyTestRequest

PromoteFromBacktestRequest