Candidate Pool
get_poolRead-onlyIdempotent
Retrieve a curated daily options-flow pool in four views: enriched analysis, raw scans, feature vectors, or a free preview, and filter by direction, ticker, score, or scan date.
Instructions
The GammaRips candidate pool for a scan date. One tool, four `view`s:
* view="enriched" (DEFAULT) — the AI-enriched pool: news, technicals,
catalyst, the recommended contract (an OTM call chosen on contract
liquidity), and the 60-day momentum feature `mom_60`. Funnel for
scan_date >= 2026-08-24 (liquid-universe era): the 100 most liquid
optionable names, BULLISH only, one call each, roughly 40-50 rows.
Liquidity decides membership, not unusual activity; the $500K UOA
floor is retired and `overnight_score>=1` is a cosmetic floor.
Earlier scan dates come from the prior UOA-gated funnel (UOA>$500K,
top-50 BULLISH); the two eras are not one population.
This is the daily candidate set your agent reasons over to its OWN
contract (see get_playbook("run-your-own-tournament")). Served from a
leakage-safe view (forward-outcome columns physically stripped);
`summary=True` gives ~21 decision columns, `fields=[...]` a strict
projection, `summary=False` full rows, `offset` pages.
* view="raw" — the wide overnight scan BEFORE the pool cut (the ranked
liquid universe for scan_date >= 2026-08-24; the market-wide
unusual-activity scan for earlier dates). Honors `direction`,
`min_score`, `ticker`, `limit`.
* view="features" — point-in-time FEATURE VECTORS from the leakage-safe
allowlist view `enriched_features_v1` (identity + features + cohort
metadata only; no outcome/label/telemetry column can appear). The
quantitative substrate for joining against query_outcomes. Lags the
live pool by ~1-2 trading days.
* view="preview" — a minimal public teaser (ticker, direction, score,
headline, directional UOA) for the most recent scan; no contract
specifics or thesis.
TIER: view="preview" is FREE (no key). The enriched / raw / features views
are the paid product — they require an active pro subscription key; an anon
call to them returns `subscription_required` (get_pool(view='preview') is
named as the free entry point).
Liquidity caveat (all views): `recommended_oi`/`recommended_volume` are
scan-time snapshots, not live values; `recommended_spread_pct` is
permanently NULL on the current data plan — re-check with get_liquidity.
Args:
view: "enriched" (default) | "raw" | "features" | "preview".
scan_date: YYYY-MM-DD (default: latest available scan for the view).
direction: "bull"/"bear" prefix filter (enriched / raw).
ticker: exact ticker filter (enriched / raw / features).
min_score: overnight_score floor (raw view only; clamped 0-10).
limit: max rows (enriched/raw clamp 1-50, features 1-100, preview 1-20).
summary: enriched only — True=compact columns, False=full rows.
fields: enriched only — explicit strict column projection.
offset: enriched only — pagination offset.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | enriched | |
| limit | No | ||
| fields | No | ||
| offset | No | ||
| ticker | No | ||
| summary | No | ||
| direction | No | ||
| min_score | No | ||
| scan_date | No |