---
title: "Registered patients list"
method: GET
path: "/api/analytics/registered-patients"
tags: ["analytics"]
---

# Registered patients list

`GET /api/analytics/registered-patients`

Registered patients (paginated) with registration data, activation milestones, and a summary activation funnel over the filtered cohort. Coordinator role sees only patients under their supervisors.

## Query parameters

- `from_date` string, date, nullable — Registration cohort start (YYYY-MM-DD).
- `to_date` string, date, nullable — Registration cohort end (YYYY-MM-DD), inclusive.
- `registration_method` string, nullable — email / google / apple / facebook.
- `registration_reason` string, nullable — Exact registration reason (motivo di iscrizione).
- `email_status` string, nullable — verified / unverified.
- `search` string, nullable — Search by name or email.
- `patient_id` string, uuid, nullable — Filter to a single patient UUID.
- `sort_by` string — Sort column.
- `sort_dir` string — Sort direction: asc or desc.
- `per_page` integer — Page size.
- `page` integer — Page number (1-based).

## Response `200`

Successful Response

- RegisteredPatientRankingResponse — Registered-patients list: summary/funnel, applied filters, paginated rows.
  - `aggregates` RegisteredPatientAggregates, required — Summary metrics and activation funnel over the filtered cohort.
    - `total_patients` integer, required — Registered patients matching filters
    - `funnel` RegisteredPatientFunnelStep[] — Activation funnel, ordered
      - `step` string, required — Stage key
      - `count` integer, required — Patients who reached this stage
      - `pct` number, nullable — Percentage of the registered cohort
    - `avg_age_at_registration` number, nullable
    - `patients_with_birth_date` integer, required
    - `age_coverage_percentage` number, required
    - `age_ranges` RegisteredPatientAgeRangeAggregate[]
      - `range` 'under_18' | '18_24' | '25_34' | '35_44' | '45_54' | '55_plus', required
      - `patients` integer, required
      - `percentage` number, required
  - `filters` RegisteredPatientFilters, required — Applied filters and pagination for the registered-patients list.
    - `from_date` string, date, nullable
    - `to_date` string, date, nullable
    - `registration_method` string, nullable
    - `registration_reason` string, nullable
    - `email_status` string, nullable — verified / unverified
    - `search` string, nullable
    - `patient_id` string, uuid, nullable
    - `sort_by` string, required
    - `sort_dir` string, required
    - `per_page` integer, required
    - `page` integer, required
    - `total` integer, required — Patients matching filters before pagination
  - `rows` RegisteredPatientRow[], required
    - `patient_id` string, uuid, required — Patient UUID
    - `user_id` string, uuid, required — User UUID
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `email` string, nullable
    - `phone` string, nullable
    - `registration_method` string, nullable — email / google / apple / facebook
    - `registration_reason` string, nullable — Reason selected at registration
    - `email_verified` boolean, nullable
    - `registered_at` string, date-time, nullable
    - `questionnaire_started_at` string, date-time, nullable
    - `questionnaire_completed_at` string, date-time, nullable
    - `story_registration_opened_at` string, date-time, nullable
    - `story_registration_completed_at` string, date-time, nullable
    - `has_opened_journey_step` boolean — Whether the patient opened at least one journey step
    - `completed_journey_steps_count` integer — Completed journey steps
    - `free_call_booked_at` string, date-time, nullable
    - `free_call_done` boolean, nullable
    - `intro_call_booked_at` string, date-time, nullable
    - `intro_call_done` boolean, nullable
    - `corabea_plus_opened_at` string, date-time, nullable
    - `has_corabea_plus_subscription` boolean, nullable
    - `last_activity_at` string, date-time, nullable
    - `tracked_sessions` integer
    - `total_foreground_seconds` integer
    - `avg_session_seconds` number, nullable

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