---
title: "List the recorded PII counts."
method: GET
path: "/api/pii-counts"
tags: ["PII Counts"]
---

# List the recorded PII counts.

`GET /api/pii-counts`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/pii-counts`
- Auth: HTTP bearer

Returns the PII type counts Philter records when the diffuseCountsEnabled setting is on, for Philter Diffuse to privatize: one entry per user's context and UTC day, with a stable id, giving for each PII type how many redactions found at least one of it, and how many found any PII. Only counts, never any PII. Sorted with sort (day, the default, context, or documents) and order (asc or desc); the default is the most recent day first. Paginated. Another user's context name and username are returned only with ADMIN_CROSS_USER_ACCESS_ENABLED; their counts always are. Narrow by day with from and to (YYYY-MM-DD, UTC, both inclusive), by context name with context (only the caller's own without cross-user access), and by username with owner. recordingEnabled says whether counts are being recorded now, so an empty listing can be told apart from recording being off; counts recorded before it was turned off are still returned. Each read is audited. The counts cover the whole deployment, so this requires an administrator as well as the pii-counts:read scope. Requires the `pii-counts:read` scope.

## Query parameters

- `from` string
- `to` string
- `context` string
- `owner` string
- `sort` string
- `order` string
- `offset` integer
- `limit` integer

## Headers

- `Authorization` string, required

## Response `200`

A page of counts, the total matching the filters, and whether counts are being recorded.

- GetPiiCountsResponse
  - `counts` PiiCountView[]: The page of counts, one per context and day, most recent day first, then by context.
    - `context` string: The context the redactions ran in. Given for the caller's own counts, and for other users' only when ADMIN_CROSS_USER_ACCESS_ENABLED is true; otherwise absent.
    - `counts` object: For each PII type, how many redactions that day found at least one of it.
    - `day` string: The UTC day the redactions ran on, as YYYY-MM-DD.
    - `id` string: Identifies this user's context and day, the same on every read, so a client paging through the counts can tell buckets apart without their names.
    - `owner` string: The username of the user whose redactions these are. Given for the caller's own counts, and for other users' only when ADMIN_CROSS_USER_ACCESS_ENABLED is true; otherwise absent.
    - `totalDocuments` integer: How many redactions that day found any PII.
    - `updatedAt` string, date-time: When a redaction was last counted.
  - `recordingEnabled` boolean: Whether Philter is recording PII counts now (the diffuseCountsEnabled setting). When it is false, no new counts are being recorded, so an empty listing does not mean no PII was found.
  - `total` integer: How many context and day aggregates match the filters.

## Other responses

- `400`: A date is not YYYY-MM-DD or is outside the years 1 to 9999, or from is after to.
- `401`: The Authorization header is absent or the API key is not recognized.
- `403`: The key does not hold pii-counts:read, or the caller is not an administrator.
- `404`: owner names no user, or another user without ADMIN_CROSS_USER_ACCESS_ENABLED.
- `406`: No representation matches Accept.
- `413`: Content Too Large
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-17** `fddc8a37e181`: 2 info
  - added the new optional `query` request parameter `order`
  - added the new optional `query` request parameter `sort`
- **2026-10-14** `1ec7bc196aca`: 1 breaking
  - removed the media type `application/json` for the response with the status `404`
- **2026-10-14** `4ff3f939d9f9`: 3 info
  - added the new optional `query` request parameter `owner`
  - added the optional property `counts/items/id` to the response with the `200` status
  - added the optional property `counts/items/owner` to the response with the `200` status
- **2026-10-12** `04a036ac1b3f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/philterd/apis/philter-api/changes/api/pii-counts/get.md)

---

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