---
title: "Signal Screener"
method: GET
path: "/screener"
tags: ["Signals"]
---

# Signal Screener

`GET /screener`

## Request

- Base URL: `https://api.falpha.ai`
- URL: `https://api.falpha.ai/screener`
- Auth: one of:
  - API key in query parameter `api_key`
  - API key in header `X-API-Key`

Cross-sectional sweep of the covered universe on the latest model-run date: rank tickers by signal strength or quality, optionally filtered by direction, sector, and a minimum quality floor. Returns at most 50 rows. **Pay-as-you-go keys** are ranked across the tickers their plan covers today, not the full universe: the response says so in `universe` (`plan_cohort`) and `universe_note`. **Billing/DB note:** `top` only truncates the response. Ranking requires reading the filtered cube date (often the full universe), so `top=10` and `top=50` do essentially the same Mongo work — see response field `scanned` and the usage `meter` (db_docs). Prefer sector filters to shrink work.

## Query parameters

- `period` string: Signal horizon: 5d, 15d, or 2m
- `regime` string: Market regime: neutral, bear, or bull
- `direction` string: Filter by signal direction: buy, sell, or any
- `sector` string, nullable: Optional sector filter (e.g. 'energy', 'informationtechnology')
- `min_quality` number, nullable: Minimum quality (Sharpe-ratio proxy) floor; rows without a quality value are excluded when set
- `rank_by` string: Ranking key: confidence (absolute signal score) or quality (Sharpe-ratio proxy)
- `top` integer: Number of rows to return (max 50). Does not reduce DB scan size.

## Response `200`

Successful Response

- ScreenerResponse
  - `as_of` string, date-time, nullable: Model-run date of the screened signal cube (latest available)
  - `period` string, required
  - `regime` string, required
  - `direction` string, required: Direction filter applied: buy, sell, or any
  - `sector` string, nullable: Sector filter applied, if any
  - `rank_by` string, required: Ranking key: confidence or quality
  - `count` integer, required
  - `scanned` integer, required: Docs considered from the cube date (after sector filter, before top truncate). `top` only caps `results` — DB work is O(scanned), so top=10 and top=50 cost the same.
  - `universe` string: Which set was ranked: 'covered_universe' (every covered ticker, after any sector filter) or 'plan_cohort' (only the tickers the caller's pay-as-you-go plan covers today). A ranking over a cohort is complete for that cohort and is NOT a ranking of the universe.
  - `universe_note` string, nullable: Plain statement of what was ranked, present whenever `universe` is not the full covered universe.
  - `results` ScreenerRow[], required
    - `ticker` string, required
    - `date` string, date-time, nullable
    - `signal` string, required: buy or sell (sign of the signal score)
    - `confidence` number, required: Absolute signal score used for ranking
    - `quality` number, nullable: Sharpe-ratio quality proxy for the row (null when unavailable)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/falpha/apis/falpha-ai-api.md) · [All operations](https://skmtc.dev/falpha/apis/falpha-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/falpha/apis/falpha-ai-api/revisions/d437fee1fac5?raw)