GET /api/v1/screener/candidates

Last verified2026-07-21

Auto-generated. This article is rebuilt from FastAPI route introspection by scripts/build_api_kb.py. Edit the route docstring in app/ and re-run the script — do not edit this file directly.

`GET /api/v1/screener/candidates`

Handler: app.screener.routes.get_screener_candidates
Methods: GET

Description

Ranked screener candidate board.

Returns candidates from screener_candidates for the requested trade_date (defaults to today ET), sorted and filtered per params.

Default sort: confluence desc → blended_score_norm desc → ticker asc (per §7.2 dashboard spec).

Filters available:

archetype — archetype ID string (e.g. A1, A2).
status — lifecycle status string.
min_confluence — minimum confluence count (integer ≥ 1).
sector — GICS sector string, case-insensitive (Session 2.2: enriched from sp500_companies.json at response time; tickers not in the map have sector=None and are excluded when this filter is set).

Sort options: confluence (default), score_norm, days_on_list, ticker, status.

Stale-board fallback: when the caller does not supply an explicit trade_date, active_only is False, and today’s board is empty (the pipeline runs at 10:30 + 17:30 ET), the route automatically returns the most recent prior board. The response envelope carries two additive fields:

is_stale_fallback — True when the fallback fires; always False on the normal path.
requested_trade_date — today’s ET date when the fallback fires; null on the normal path.

These fields default to False / null on the normal path so existing consumers that do not read them are byte-compatible.

Board rank + movement (PR-S, additive). Every candidate row carries three computed-at-query-time fields (NOT persisted):

rank — the ticker’s 1-based position on the served board, in the canonical board order (confluence_count desc, blended_score_norm desc, ticker asc).
rank_prior — the ticker’s rank on the prior populated board, or null when the ticker was absent yesterday.
rank_delta — rank_prior - rank (POSITIVE = moved UP the board), or null when there is no prior rank.

What-changed block (PR-S, additive). The response envelope carries a what_changed object describing day-over-day board churn: {prior_trade_date, new_today, requalified, dropped, promoted_today} — distinct, sorted ticker lists. new_today = active today and first-seen today; requalified = status new today with an earlier first-seen; dropped = active on the prior board, not active today; promoted_today = rows promoted on the served date. A null prior date yields empty lists.

Parameters

In	Name	Type	Default	Description
query	`archetype`	`Optional[str]`		Filter by archetype: canonical descriptive ID (e.g. ‘oversold_sympathy’) or short code (e.g. ‘A2’, back-compat — translated to the descriptive ID).
query	`direction`	`Optional[str]`		Filter by candidate direction (Session 5.3 bidirectional board): ‘long’ (long_recovery), ‘short’ (short_fragility), ‘neutral’ (neutral_coiling), or ‘all’ (default — no filter). Canonical values pass through. Omitted = unchanged response (back-compat).
query	`status`	`Optional[str]`		Filter by lifecycle status: new, persisting, decayed, exited, promoted.
query	`sector`	`Optional[str]`		Filter by GICS sector string (case-insensitive; derived from sp500_companies.json current-GICS map — Session 2.2).
query	`min_confluence`	`Optional[int]`		Minimum confluence_count (integer >= 1).
query	`sort`	`str`	`'confluence'`	Sort order: confluence (default), score_norm, days_on_list, ticker, status.
query	`trade_date`	`Optional[str]`		Snapshot date YYYY-MM-DD ET. Defaults to today ET.
query	`limit`	`int`	`200`	Maximum rows to return.
query	`active_only`	`bool`	`False`	When true, return only rows with status in (new, persisting), using point-in-time latest row per (ticker, archetype).
query	`s2_only`	`bool`	`False`	When true, restrict the board to ACTIVE S2 members (the gated winners tracked in screener_s2_membership). This is the default screener-page board view; pass false for the full candidate event-log.
query	`max_tickers`	`Optional[int]`		Cap the board to the top-N distinct TICKERS in the current sort order (their full archetype-row set is kept). The screener page passes funnel.board_top_n (~30) for the ‘best N’ winners view; the stale-fallback / full-log views leave it unset.

Curl

curl -s https://bigclawd.com/api/v1/screener/candidates

Signals:get_screener_candidates