---
title: "List document favoriters"
method: GET
path: "/v1/documents/{documentId}/favorites"
tags: ["Document favorites"]
---

# List document favoriters

`GET /v1/documents/{documentId}/favorites`

<Note>
  This endpoint requires **Manager** or **Owner** permissions on the requested document.
</Note>

Lists users who have favorited a published document, paginated and sorted by `favoritedAt`.

Use this endpoint when you need to know "who favorited document X" — for example, a content-migration script that preserves favorites when replacing a document needs to call this once per document, rather than iterating every user in the organization.

## Path parameters

- `identifier` string, required

## Query parameters

- `cursor` string, nullable
- `pageSize` integer
- `sortDirection` 'asc' | 'desc'

## Response `200`

Successfully retrieved list of users who favorited the document

- object
  - `pageInfo` PageInfo, required — Pagination information for paginated responses.
    - `hasNextPage` boolean — Indicates if there are more records available.
    - `nextCursor` string, nullable — Cursor for the next page of results. `null` if no more results.
    - `pageSize` integer — Number of records per page.
    - `totalRecords` integer — Total number of records matching the query.
  - `records` object[], required
    - `userId` string, required — Membership ID of the favoriting user.
    - `name` string, required — User's display name.
    - `email` string, required — User's email address.
    - `favoritedAt` string, date-time, required — ISO 8601 timestamp recording when the user favorited the document.

## Other responses

- `400` — Bad Request. Invalid query parameters. Possible causes: - Unparseable cursor - Out-of-range `pageSize` (must be 1-100) - Invalid `sortDirection` (must be `asc` or `desc`) - Unknown query parameter
- `401` — Missing authentication
- `403` — Forbidden. Possible causes: - Caller lacks `MANAGER` permission on the document - Used a user-scoped (personal access token) API key
- `404` — Document not found (or unpublished)
- `405` — Method Not Allowed - Invalid HTTP method for this endpoint
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)