---
title: "Shields.io-style rank badge (JSON)"
method: GET
path: "/rankings/{ticker}/badge"
tags: ["Risk Metrics"]
---

# Shields.io-style rank badge (JSON)

`GET /rankings/{ticker}/badge`

## Request

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

Public JSON for [Shields Endpoint badges](https://shields.io/badges/endpoint-badge). No API key by default; optional shared secret via env `RANKINGS_BADGE_TOKEN` and query `token=`. Defaults: metric=subsector_residual, cohort=subsector, window=252d. `rank_percentile` 100 = best. Cached at the edge; per-IP rate limit when Upstash Redis is configured (`RANKINGS_BADGE_IP_RPM`, default 120).

## Path parameters

- `ticker` string, required

## Query parameters

- `token` string
- `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`

Shields endpoint JSON (schemaVersion 1).

- object
  - `schemaVersion` 1, required
  - `label` string
  - `message` string
  - `color` string
  - `isError` boolean

## Other responses

- `400`: Invalid ticker or query parameter.
- `401`: Missing or invalid token when RANKINGS_BADGE_TOKEN is set.
- `404`: Ticker or ranking row not found.

---

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