---
title: "Cross-sectional rankings screen"
method: POST
path: "/rankings/screen"
tags: ["Risk Metrics"]
---

# Cross-sectional rankings screen

`POST /rankings/screen`

## Request

- Base URL: `https://riskmodels.app/api`
- URL: `https://riskmodels.app/api/rankings/screen`
- Auth: HTTP bearer

Full-universe rank screen from `ds_rankings` at one `teo` (default latest). Applies server-side `min_percentile`, `decile` (1 = best decile), and optional `sector_filter` (sector ETF on `symbols.sector_etf`), then returns up to 500 names sorted by ascending `rank_ordinal`. Same `rank_percentile` rule as GET /rankings/top (100 = best).

## Request body

- object
  - `metric` 'mkt_cap' | 'gross_return' | 'sector_residual' | 'subsector_residual' | 'er_l1' | 'er_l2' | 'er_l3', required
  - `cohort` 'universe' | 'sector' | 'subsector', required
  - `window` '1d' | '21d' | '63d' | '252d', required
  - `as_of` string, date: Observation date (default latest teo in zarr).
  - `min_percentile` number
  - `decile` integer
  - `sector_filter` string: Sector ETF ticker (e.g. XLK).
  - `limit` integer

## Response `200`

Filtered cross-section rows and counts.

- object
  - `teo` string, date
  - `metric` string
  - `cohort` string
  - `window` string
  - `limit` integer
  - `min_percentile` number, nullable
  - `decile` integer, nullable
  - `sector_filter` string, nullable
  - `universe_size` integer
  - `matched_count` integer
  - `universe` string
  - `data_source` string
  - `rankings` object[]
    - `symbol` string
    - `ticker` string
    - `rank_ordinal` integer
    - `cohort_size` integer, nullable
    - `rank_percentile` number, nullable
  - `_metadata` object
  - `_agent` AgentMeta: Per-request billing and telemetry metadata appended to metered responses.
    - `cost_usd` number, float: Cost deducted from prepaid balance for this request. 0 if served from cache.
    - `latency_ms` integer: Server processing time in milliseconds.
    - `request_id` string: Unique request identifier for support lookups.
    - `confidence` object
      - `overall` number, float
      - `factors` object
    - `data_freshness` string, date-time: ISO timestamp of the data's as-of datetime.
    - `billing_code` string: Internal billing classification for this request type.
    - `cache_status` 'HIT' | 'MISS' | 'BYPASS': Whether this response was served from cache.
    - `llm_cost_usd` number, float: POST /chat only: portion of cost from LLM token billing (estimated preflight charge).
    - `tool_cost_usd` number, float: POST /chat only; sum of internal data tool charges for this turn.
    - `tool_calls` integer: POST /chat only; number of tool invocations in this request.

## Other responses

- `400`: Invalid request body.
- `402`: Insufficient balance.
- `404`: Rankings data unavailable.

---

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