> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Patient Cohorts

> Define and manage named patient populations for HEDIS reporting, VBP attribution, and outreach campaigns.

The Patient Cohorts screen (`/cl/cohorts`) lists all patient cohort definitions for the organization and provides controls to create new cohorts and filter the list by status.

## Overview

The page queries `cl_patient_cohorts` via `useCohortList`, which supports paginated and filterable fetches (default page size 25, ordered by `updated_at` descending). Cohorts are displayed in a table with columns for Name, Type (`definition_type`), Status, Version, and Updated date. A status filter dropdown lets users show all cohorts or filter by `draft`, `active`, or `archived`. Users with `cl.cohort.create` see a "Create cohort" button that opens `CohortFormSheet` in a side panel. Each cohort name is a link to `/cl/cohorts/:cohortId`. Cohorts with a `description` show a truncated subtitle under the name.

## Who it's for

Requires permission: `cl.cohort.view`

## Before you start

You must hold the `cl.cohort.view` permission. Creating new cohorts additionally requires `cl.cohort.create`. The cohort list is scoped to your organization.

## Steps

<Steps>
  <Step title="Navigate to /cl/cohorts">
    Open the Clinical module and navigate to Patient Cohorts. The page loads all cohorts for your organization.
  </Step>

  <Step title="Filter by status">
    Use the status dropdown to narrow the list to `draft`, `active`, or `archived` cohorts. The default view shows all statuses.
  </Step>

  <Step title="Open a cohort">
    Click the cohort name link in the table to navigate to the cohort detail page at `/cl/cohorts/:cohortId`.
  </Step>

  <Step title="Create a new cohort">
    Click "Create cohort" (requires `cl.cohort.create`) to open the `CohortFormSheet`. Complete the form fields and save to add the cohort to the list.
  </Step>
</Steps>

## Key concepts

<AccordionGroup>
  <Accordion title="Cohort status values">
    The status filter and badge display three values sourced from `COHORT_STATUS_LABELS`: `draft` (secondary badge), `active` (default badge), and `archived` (outline badge).
  </Accordion>

  <Accordion title="Definition types">
    The Type column renders a badge using `COHORT_DEFINITION_TYPE_LABELS`. If the type key is not in the map, the raw `definition_type` value is displayed.
  </Accordion>

  <Accordion title="Pagination">
    `useCohortList` supports `page` and `pageSize` parameters (default: page 1, size 25). The list page does not render explicit pagination controls in this version.
  </Accordion>

  <Accordion title="Empty state">
    When no cohorts exist or match the filter, the page shows: "No cohorts yet — Define patient populations for HEDIS reporting, VBP attribution, and outreach campaigns."
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Clinical" icon="stethoscope" href="/cl/overview">
    Overview of the Clinical core.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/cl.tsx
  * src/cores/cl/pages/CohortListPage.tsx
  * src/cores/cl/hooks/cohorts/useCohortList.ts
  * src/cores/cl/types/cohorts.ts
  * src/cores/cl/components/cohorts/CohortFormSheet.tsx
</Accordion>