---
title: "List patients"
method: GET
path: "/workspaces/{workspaceId}/patients"
tags: ["patients"]
---

# List patients

`GET /workspaces/{workspaceId}/patients`

## Request

- Base URL: `https://vetnio.com/api/v2`
- URL: `https://vetnio.com/api/v2/workspaces/{workspaceId}/patients`
- Auth: HTTP bearer

Returns one page of the workspace's patients, each with its owner's name. Combine `searchQuery` (a case-insensitive substring of the patient name, identifier or owner name) with the optional filters; all supplied conditions must match. Ordered by `sort`, newest first by default. Paginate with `page` and `pageSize` and use `totalCount` to know when to stop. Every workspace member can list all patients.

## Path parameters

- `workspaceId` string, required: Identifier of the workspace (clinic) that owns the patients and clients. The caller must be a member of it; patients and clients are shared by all members of the workspace.

## Query parameters

- `page` integer: 1-based page number. A page past the end returns an empty `patients` array.
- `pageSize` integer: Patients per page, 1 to 100.
- `searchQuery` string: Case-insensitive substring matched against the patient name, the patient identifier (for example a microchip number) and the owner's name. Up to 200 characters, used as typed (not trimmed); `%` and `_` act as wildcards. Species is not searched; use `speciesFilter`.
- `speciesFilter` string: Species to filter by, case-insensitive. A known species name in any language Vetnio supports (for example `Dog`, `dog` or `Hund`) matches every stored spelling of that species, with or without a ` - <breed>` suffix. Any other value must match the stored species exactly (case-insensitive), optionally followed by ` - <breed>`.
- `insuranceFilter` string: Insurance company name; must match the stored value exactly, ignoring case.
- `genderFilter` string: Sex value; must match the stored value exactly, ignoring case (for example `Female Neutered` does not match `Female`).
- `hasWeightFilter` 'yes' | 'no': Filter on whether a weight is recorded: - `yes` — only patients with a non-empty weight. - `no` — only patients without a weight. Omit to include both.
- `sort` 'date_added' | 'last_visit' | 'name': Order of the results (default `date_added`): - `date_added` — newest patients first. - `last_visit` — patients with the most recent consultation first; patients without consultations last. - `name` — alphabetical by name, case-insensitive; patients without a name last. Ties are broken by newest first.

## Response `200`

Paginated patient list with total count for pagination.

- PatientList: One page of patients plus the total number of matches.
  - `patients` object[], required: The patients on the requested page, in the requested order. Empty when the page is past the end.
    - `id` string, required: Patient id (UUID).
    - `name` string, nullable, required: The animal's name, or `null`.
    - `species` string, nullable, required: Species as stored (see `Patient.species`), or `null`.
    - `breed` string, nullable, required: Breed, or `null`.
    - `dateOfBirth` string, nullable, required: Date of birth (`YYYY-MM-DD`), or `null`.
    - `gender` string, nullable, required: Sex and neuter status as stored, or `null`.
    - `weight` string, nullable, required: Body weight as stored, including the unit, or `null`.
    - `identifier` string, nullable, required: Identifier such as a microchip number, or `null`.
    - `insurance` string, nullable, required: Insurance company name, or `null`.
    - `clientId` string, nullable, required: Id of the owner (client), or `null`.
    - `clientName` string, nullable, required: The owner's name, included so a list can be shown without fetching each client. `null` when there is no owner or the owner has no name.
    - `createdAt` string, nullable, required: When the patient was created (ISO-8601), or `null` for very old records.
    - `updatedAt` string, nullable, required: When the patient was last changed (ISO-8601).
  - `totalCount` number, required: Number of patients matching the search and filters across all pages. The number of pages is `ceil(totalCount / pageSize)`.

## Other responses

- `400`: Invalid input data
- `401`: Authorization not provided
- `403`: Insufficient access
- `404`: Not found
- `500`: Internal server error

---

[API](https://skmtc.dev/vetnio/apis/vetnio-api.md) - [All operations](https://skmtc.dev/vetnio/apis/vetnio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vetnio/apis/vetnio-api/revisions/d004afd5617d?raw)