# List change history

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

`GET /v1/slim/change-history`

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

**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.

## Behaviour

- Each row is one recorded change. `details.key` names the change and `details.values` holds the values to put into its message.
- Rows are sorted by recording time, newest first. `sort=asc` returns the same rows oldest first. Rows recorded in the same millisecond keep one fixed order, so paging never skips or repeats 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 only project-wide changes: organization threshold edits, device, location and zone lifecycle changes, and user and role changes. `scope=all` (the default) returns every row.
- `types=Access` lists the user and role changes: a user invited (`userInvited`), renamed (`userRenamed`), moved to another role (`userRoleChanged`) or removed (`userRemoved`), and a role created (`roleCreated`), given other permissions (`rolePermissionsChanged`) or deleted (`roleDeleted`). They name users and roles by name and concern no resident.
- `userId`, `residentId`, `deviceId`, `locationId` and `zoneId` are ids, not references. Each takes several ids, repeated or comma-separated, and matches a row concerning any of them. Different filters combine with AND. `userId` matches the practitioner who made the change. A value that is not an id answers 422.
- `relatedTo` takes typed references (`Patient/<id>`, `Device/<id>`, `Location/<id>`, `Organization/<id>`), repeated or comma-separated, and returns every row concerning any of them, once each.
- `actions` keeps the kinds of change you name: `created`, `deleted`, `renamed`, `moved`, `assigned`, `unassigned`, `discharged`, `reactivated`, `thresholdChanged`. Rows recorded before this filter shipped carry no kind, so they never match it.
- `resident` on a row is the resident it concerns, `{patientId, residentId}`, or null when it concerns none. `residentId` inside it is their Resident ID, or null when they have none: show a placeholder, never a name. The flat `residentId` carries the same Resident ID, or is empty. Neither is ever a name or an internal id.
- Threshold and Signals settings changes made through the Signals API are listed as Threshold changes, with the reason given.
- Changes a device makes itself, such as a baseline re-push after a new 7-day mean, are never listed, and never counted in `total`.
- 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

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/change-history?types=Threshold&types=Resident&page=0&count=50' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
```