Scan a single condition for predictive power across historical data — use this BEFORE building strategies to test whether a condition actually predicts forward returns. Returns statistical significance (p-value), win rate, Sharpe, and consistency across time periods.

Verdicts — results include a warnings list and a reliable boolean. If reliable=false the signal has data-quality issues and the verdict is needs_more_data. If the only hard diagnostic is no_fires (valid condition, sufficient data, but it never evaluated true) the verdict is condition_never_fired — rethink the condition (relax thresholds, check for internal contradictions like "trending up AND deeply oversold") rather than extending the window. Every run is persisted as a ScanRun with an auto-computed verdict, so every call has a poll-able handle.

Response envelope — {batch_id, count, status, scan_run_ids, results, top_results, errors, message}. top_results is the top ~10 rows by Sharpe over the full completed set (even when results is truncated). status is one of:

• completed — every run terminal, no failures; results inline.
• partial — some terminal, some still running or failed; poll with get_scan_batch(batch_id).
• pending — sync-wait timed out before any run completed.

Sweep mode — put a list in any scalar param to scan variants, e.g. {"indicator": "rsi", "period": [10, 14, 20]} generates 3 runs. Use sweep_mode="zip_by_index" to pair lists element-wise instead of the cartesian product.

Multi-symbol — pass symbols=["AAPL", "TSLA"] to scan across assets; combines with sweep (2 symbols × 3 periods = 6 runs). Batch runs (sweep or multi-symbol) require project_id and sync-wait for terminal status; fall back to get_scan_batch(batch_id) on timeout.

Scannable conditions — only conditions valid as backtest entry conditions. The scan loop has no position state, fills, or equity curve, so position/exit refs (live_position, entry_bar, trade_history, fixed_targets, trailing_stop), always_true, and regime_filter mode=level are rejected. See builder_discover(action='get', ref=) for available condition types.

Key params — resolution (1m/5m/1h/4h/1d), start_date/end_date (YYYY-MM-DD), symbol xor symbols, horizons (forward bars, default [1, 5, 10, 20]), filter_condition (ANDed with the main condition), max_combinations (default 200), min_occurrences (default 0; applied ONLY on the inline single-symbol/single-variant path, where a result below the threshold is marked needs_more_data — batch scans (multi-symbol or sweep) ignore it, pass min_occurrences to get_scan_batch instead).