---
title: "Patient app-access ranking"
method: GET
path: "/api/analytics/patient-access"
tags: ["analytics"]
---

# Patient app-access ranking

`GET /api/analytics/patient-access`

Ranking of patients by app accesses with aggregates. Optional date range filters the access counts only (recency stays absolute). Coordinator role sees only patients under their supervisors.

## Query parameters

- `from_date` string, date, nullable — Range start for access counts (YYYY-MM-DD).
- `to_date` string, date, nullable — Range end for access counts (YYYY-MM-DD).
- `target_statuses` string, nullable — Comma-separated status keys (e.g. attivo,mai pagato). Empty for all.
- `frequency` string, nullable — Comma-separated frequency levels (never,rarely,occasional,frequent,always), relative to the selected period. Needs from/to.
- `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

- PatientAccessRankingResponse — App-access ranking: aggregates, applied filters, paginated rows.
  - `aggregates` PatientAccessAggregates, required — Overall and per-status aggregates for the filtered patient set.
    - `total_patients` integer, required — Patients matching filters
    - `total_accesses` integer, required — Total accesses in the selected range if set, else all-time, matching filters
    - `accesses_all_time` integer, required — All-time total accesses matching filters (always, regardless of the selected range)
    - `accesses_last_90d` integer, required — Total accesses in the last 90 days matching filters
    - `accesses_last_30d` integer, required — Total accesses in the last 30 days matching filters
    - `accesses_last_7d` integer, required — Total accesses in the last 7 days matching filters
    - `avg_accesses_per_patient` number, nullable — Avg accesses per patient matching filters
    - `avg_accesses_before_call` number, nullable — Avg accesses before the call matching filters
    - `avg_days_registration_to_call` number, nullable — Avg days registration to call booking matching filters
    - `by_status` PatientAccessStatusAggregate[]
      - `status` string, required — Base status label
      - `patients` integer, required — Patients in this status
      - `avg_accesses_before_call` number, nullable — Avg accesses before the call
      - `avg_days_registration_to_call` number, nullable — Avg days from registration to call booking
    - `accesses_by_client` PatientAccessClientAggregate[]
      - `client` 'native_ios' | 'native_android' | 'web_mobile' | 'web_tablet' | 'web_desktop', required
      - `accesses` integer, required
      - `percentage` number, required
    - `usage` PatientUsageAggregates, required
      - `tracked_sessions` integer, required
      - `tracked_patients` integer, required
      - `tracking_coverage_percentage` number, required
      - `total_foreground_seconds` integer, required
      - `avg_session_seconds` number, nullable
      - `avg_sessions_per_tracked_patient` number, nullable
      - `avg_seconds_per_tracked_patient` number, nullable
  - `filters` PatientAccessFilters, required — Applied filters and pagination for the access ranking.
    - `from_date` string, date, nullable — Range start for access counts
    - `to_date` string, date, nullable — Range end for access counts
    - `target_statuses` string[] — Status filter keys
    - `frequency` string[] — Frequency level filter (never/rarely/occasional/frequent/always)
    - `patient_id` string, uuid, nullable — Single patient filter
    - `sort_by` string, required — Sort column
    - `sort_dir` string, required — Sort direction (asc/desc)
    - `per_page` integer, required
    - `page` integer, required
    - `total` integer, required — Patients matching filters before pagination
  - `rows` PatientAccessRow[], required — Paginated patient rows
    - `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
    - `patient_status` string[], nullable — Current status keys
    - `total_accesses` integer, required — Accesses in the selected range if set, else all-time
    - `accesses_all_time` integer, required — All-time accesses (always, regardless of the selected range)
    - `accesses_last_90d` integer, required — Accesses in the last 90 days
    - `accesses_last_30d` integer, required — Accesses in the last 30 days
    - `accesses_last_7d` integer, required — Accesses in the last 7 days
    - `accesses_before_call` integer, nullable — Accesses before the first CALL_CONOSCITIVA booking
    - `first_access_at` string, date-time, nullable — First access after tracking started
    - `last_access_at` string, date-time, nullable — Most recent access
    - `days_since_last_access` integer, nullable — Days since last access
    - `avg_accesses_per_week` number, nullable — Average accesses per week
    - `avg_accesses_per_month` number, nullable — Average accesses per month
    - `registered_at` string, date-time, nullable — Patient registration date
    - `first_call_booking_at` string, date-time, nullable — When the patient booked the first CALL_CONOSCITIVA
    - `days_registration_to_call` integer, nullable — Days from registration to CALL_CONOSCITIVA booking
    - `frequency` string, nullable — Access frequency in the selected period by access rate (accesses/day): never/rarely/occasional/frequent/always (null without a date range)
    - `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)