---
title: "Cross-sectional rankings snapshot"
method: GET
path: "/rankings/{ticker}"
tags: ["Risk Metrics"]
---

# Cross-sectional rankings snapshot

`GET /rankings/{ticker}`

## Request

- Base URL: `https://riskmodels.app/api`
- URL: `https://riskmodels.app/api/rankings/{ticker}`
- Auth: HTTP bearer

Latest V3 cross-sectional ranks from `security_history` for the ticker’s symbol. Optional query filters narrow to one metric, cohort, and/or window; omit them for the full grid. See `#/components/schemas/RankingMetricKeys` for key patterns. `rank_percentile` is 100 = best.

## Path parameters

- `ticker` string, required

## Query parameters

- `metric` 'mkt_cap' | 'gross_return' | 'sector_residual' | 'subsector_residual' | 'er_l1' | 'er_l2' | 'er_l3'
- `cohort` 'universe' | 'sector' | 'subsector'
- `window` '1d' | '21d' | '63d' | '252d'

## Response `200`

Rankings and lineage metadata.

- object
  - `ticker` string
  - `symbol` string
  - `teo` string, date, nullable
  - `rankings` object[]
    - `metric` string
    - `cohort` string
    - `window` string
    - `rank_ordinal` integer, nullable
    - `cohort_size` integer, nullable
    - `rank_percentile` number, nullable
  - `filters` object
    - `metric` string, nullable
    - `cohort` string, nullable
    - `window` string, 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 query parameter.
- `401`: Missing or invalid Bearer token.
- `402`: Insufficient balance.
- `404`: Ticker not found.
- `429`: Rate limit exceeded.

---

[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)