---
title: "Cohort roster and variable catalogue (discovery)"
method: GET
path: "/cohorts/roster"
tags: ["Risk Metrics"]
---

# Cohort roster and variable catalogue (discovery)

`GET /cohorts/roster`

## Request

- Base URL: `https://riskmodels.app/api`
- URL: `https://riskmodels.app/api/cohorts/roster`
- Auth: HTTP bearer

The addressable cohorts, their parent links, the variable catalogue, and the
interpretation notes that govern correct use — including the no-intercept
contract read directly from the store's own metadata. Free; call this before
`/cohorts` to learn what may be requested and what the numbers mean.

This lists the public cohorts only. It is not a census of the underlying store.

## Response `200`

Cohort roster

- CohortRosterResponse: Addressable cohorts, their parent links, the variable catalogue, and the interpretation notes. Call this before /cohorts to learn what may be requested and what the numbers mean.
  - `cohorts` object[]
    - `ticker` string
    - `level` 1 | 2
    - `parent` string, nullable
    - `valid_from` string, date, nullable
    - `valid_to` string, date, nullable: null = still open.
  - `variables` object
    - `distribution` string[]
    - `breadth` string[]
    - `factor` string[]
  - `disclosures` CohortDisclosures: Interpretation notes that govern correct use of the cohort statistics. `no_intercept_contract` and `return_source_legend` are read from the store's own attributes rather than restated here, so they cannot drift from the data they describe.
    - `no_intercept_contract` string: ERM3 residuals are estimated WITHOUT an intercept and therefore retain each stock's alpha. The cross-sectional mean is NOT zero. If you are building relative-ranking signals, demean first using `residual_mean`.
    - `return_source_legend` string: Meaning of each `factor_source` code.
    - `coverage` string: Cohort coverage of the eligible universe (~88%) and the date from which full factor richness begins.
    - `dispersion_use` string: How to use `residual_sd` — a conditioning and allocation variable, not an alpha source.
    - `er_sign` string: Why `cohort_ER` is an incremental attribution that can be negative, and how it differs from `linked_beta_r2`.
    - `thin_cohorts` string: Why to filter on `min_names` and prefer `n_effective` for breadth.
  - `universe` string
  - `panel` string[], nullable: [first, last] date in the store.

## Other responses

- `404`: Cohort data unavailable
- `429`: Rate limit exceeded.
- `500`: Internal error

---

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