---
title: "Patients of a retention cell"
method: GET
path: "/api/analytics/retention/cohort-patients"
tags: ["analytics"]
---

# Patients of a retention cell

`GET /api/analytics/retention/cohort-patients`

Paginated patients of a single retention cell: the cohort registered at cohort_start that was active at the given period_offset. Coordinator role sees only patients under their supervisors.

## Query parameters

- `cohort_start` string, date, required — Cohort registration period start (YYYY-MM-DD): week Monday or month first day.
- `period_offset` integer, required — Periods after registration (the matrix column).
- `granularity` string — Cohort granularity: week or month (must match the matrix).
- `target_statuses` string, nullable — Comma-separated status keys (e.g. attivo,mai pagato). Empty for all.
- `per_page` integer — Page size.
- `page` integer — Page number (1-based).

## Response `200`

Successful Response

- RetentionCohortPatientsResponse — Paginated patients of one retention cell: a cohort active at a given period offset.
  - `granularity` string, required — Cohort granularity: week or month
  - `cohort_start` string, date, required — Registration period from_date of the cohort
  - `period_offset` integer, required — Periods after registration (the cell column)
  - `period_start` string, date, required — Start of the period at that offset (cohort_start + period_offset)
  - `total` integer, required — Patients in the cell (matches the matrix cell count)
  - `per_page` integer, required
  - `page` integer, required
  - `patients` RetentionCohortPatientRow[] — Paginated patients
    - `patient_id` string, uuid, required — Patient UUID
    - `user_id` string, uuid, required — User UUID
    - `first_name` string, nullable — Patient first name
    - `last_name` string, nullable — Patient last name
    - `email` string, nullable — Patient email
    - `phone` string, nullable — Patient phone
    - `patient_status` string[], nullable — Current status keys
    - `registered_at` string, date-time, nullable — Registration date
    - `last_access_at` string, date-time, nullable — Most recent app access

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/corabea/apis/corabea-api.md) · [All operations](https://skmtc.dev/corabea/apis/corabea-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/corabea/corabea-api/revisions/13c1bce1bdc4/schema)