# List change history

Canonical page: https://docs.ovok.com/slim-apis/audit/list-change-history

| Method | Path |
| --- | --- |
| `GET` | `/v1/slim/change-history` |

[Authentication](/authentication) · [Access policies](/access-policies)

Lists the recorded changes to thresholds, locations, zones, devices, residents, users and roles in your project. Use it for the resident and administration change-history screens.

`Access` rows cover users invited (`userInvited`), renamed (`userRenamed`), moved to another role (`userRoleChanged`) or removed (`userRemoved`), and roles created (`roleCreated`), given other permissions (`rolePermissionsChanged`) or deleted (`roleDeleted`). Users and roles are named by name; Access rows do not involve a resident.

**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Provenance:read`. Only the Admin and System Owner access policies carry it, so other users get no change history.
**Scope:** the caller's project (from the token). The rows are read with your token, so you only see changes recorded in your project.

## Request [#request]

### Query parameters [#query-parameters]

Unknown query parameters are ignored.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Zero-based page number. Default `0`, minimum `0`. |
| `count` | `integer` | No | Rows per page. Default `50`, minimum `1`, maximum `100`. |
| `types` | `"Threshold"` \| `"Location"` \| `"Zone"` \| `"Device"` \| `"Resident"` \| `"Access"` | No | Keep only these change types. Repeat the parameter to pass several. Omit for all types. |
| `scope` | `"all"` \| `"global"` | No | `all` returns every row. `global` keeps only project-wide changes. Default `all`. |
| `userId` | `string` | No | One or more user ids, repeated or comma-separated. Every value must be an id. |
| `residentId` | `string` | No | One or more resident ids, repeated or comma-separated. Every value must be an id. |
| `deviceId` | `string` | No | One or more device ids, repeated or comma-separated. Every value must be an id. |
| `locationId` | `string` | No | One or more location ids, repeated or comma-separated. Every value must be an id. |
| `zoneId` | `string` | No | One or more zone ids, repeated or comma-separated. Every value must be an id. |
| `relatedTo` | `string` | No | One or more typed references (`Patient/<id>`, `Device/<id>`, `Location/<id>` or `Organization/<id>`), repeated or comma-separated. |
| `actions` | `string` | No | One or more of `created`, `deleted`, `renamed`, `moved`, `assigned`, `unassigned`, `discharged`, `reactivated` or `thresholdChanged`. Rows recorded before this filter shipped have no action and never match. |
| `sort` | `"asc"` \| `"desc"` | No | Recording-time order. Default `desc`. |
| `startDate` | `string (ISO 8601 date-time)` | No | Only changes recorded at or after this time. Default: 30 days before now. |
| `endDate` | `string (ISO 8601 date-time)` | No | Only changes recorded at or before this time. |

## Behaviour [#behaviour]

- Each row is one recorded change. `details.key` names the change and `details.values` holds the values to put into its message. See the [change-history key catalogue](/slim-apis/audit/change-history-keys) for the keys and their values.
- Rows are sorted by recording time, newest first by default. Use `sort=asc` for oldest first. Rows with the same millisecond always keep a fixed order, so paging does not skip or repeat a row.
- Without `startDate`, the list starts 30 days before now. `endDate` is optional. Both bounds are inclusive.
- `types` limits the rows to the given change types. Omit it to get every type. Repeat the parameter to pass several types.
- `scope=global` keeps project-wide changes, including organization threshold edits, device, location and zone lifecycle changes, and Access changes to users and roles. `scope=all` (the default) returns every row.
- Each id filter accepts one or more ids, repeated or comma-separated. Values within one filter are ORed; different filters are combined with AND. `userId` matches the practitioner who made the change.
- `relatedTo` matches a row once if it concerns any named resource. Use `actions` to filter by change kind. Older rows without an action never match `actions`.
- Changes a device makes itself, such as a baseline re-push after a new 7-day mean, are never listed or counted.
- Unknown query parameters are ignored.
- `page` is zero-based and `count` defaults to 50, maximum 100. `total` counts only rows the list can return and never exceeds 10,000. Pages from offset 10,000 on come back empty, so narrow the filters or the date range to reach older rows.

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/change-history?page=0&count=50' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — Change history rows retrieved successfully.

```json
{
  "total": 2,
  "page": 0,
  "count": 50,
  "resources": [
    {
      "id": "6e1f3a9c-2b7d-4c58-8a40-d3b9e5f17c26",
      "type": "Device",
      "user": "Alex Example",
      "residentId": "demo-resident",
      "resident": { "patientId": "6e4f3a20-1b8c-4d7e-a2f1-5c9b0d3e6f18", "residentId": "demo-resident" },
      "deviceId": "Demo/1000001",
      "locationId": null,
      "zoneId": null,
      "time": "2026-10-09T07:45:12.000Z",
      "details": {
        "key": "residentDeviceAssigned",
        "values": { "resident": "demo-resident", "deviceId": "Demo/1000001" }
      }
    },
    {
      "id": "1d8a2f60-3b5c-4e79-9a01-6c2d8f4b7e35",
      "type": "Access",
      "user": "Alex Example",
      "residentId": "",
      "resident": null,
      "deviceId": "",
      "locationId": null,
      "zoneId": null,
      "time": "2026-10-09T07:45:11.000Z",
      "details": {
        "key": "userRoleChanged",
        "values": { "user": "Alex Example", "fromRole": "Nurse", "toRole": "Admin" }
      }
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Number of rows the list can return across all pages. Never more than 10,000. |
| `page` | `integer` | Page number of this response. |
| `count` | `integer` | Page size you asked for. The page can hold fewer rows. |
| `resources` | `object[]` | The rows of this page in the order selected by `sort`. |
| `resources[].id` | `string` | Id of the change record. |
| `resources[].type` | `"Threshold"` \| `"Location"` \| `"Zone"` \| `"Device"` \| `"Resident"` \| `"Access"` | Change type. |
| `resources[].user` | `string` | Display name of the person who made the change. Empty string when there is none. |
| `resources[].residentId` | `string` | The affected resident's Resident ID, or an empty string. It is never a name or an internal patient id. |
| `resources[].resident` | `object` \| `null` | `{ patientId, residentId }`, or `null` when no resident is involved. `residentId` is the Resident ID, or `null` when the resident has none; it is never a name. |
| `resources[].deviceId` | `string` | The affected device's name, not the device id. The device id for old rows that have no name. Empty string when no device is involved. |
| `resources[].locationId` | `string \| null` | Name of the room the change is about. For a move, the room the resident left. `null` when there is none. |
| `resources[].zoneId` | `string \| null` | Name of the zone the change is about. For a move, the zone the resident left. `null` when there is none. |
| `resources[].time` | `string (ISO 8601 date-time)` | When the change was recorded. |
| `resources[].details` | `object` | What changed, as a message key and its values. |
| `resources[].details.key` | `string` | Message key, such as `residentDeviceAssigned`. `genericMessage` for old rows that carry plain text. |
| `resources[].details.values` | `object` | Values for the message, keyed by name. Each value is a `string`, a `number` or `null`. Left out when the message has none. For `genericMessage` it holds `message`. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, or you lack `Provenance:read`. |
| [`422`](/errors/validation-failed) | A value in an id filter is not an id, `relatedTo` is invalid, `actions` contains an unknown value, or another query parameter fails validation. |
