---
title: "List users who favorited the document"
method: GET
path: "/api/v1/documents/{identifier}/favorites"
tags: ["Documents"]
---

# List users who favorited the document

`GET /api/v1/documents/{identifier}/favorites`

Lists users who have favorited the document, paginated and sorted by favoritedAt. Document-centric counterpart to GET /api/v1/documents?include=onlyFavorites: useful for migration scripts that need to preserve favorites when replacing documents, without iterating every user in the organization.

## Path parameters

- `identifier` string, required — Document identifier (either document ID or identifier slug)

## Query parameters

- `cursor` string — Cursor for pagination (from previous response nextCursor)
- `pageSize` integer — Number of results per page (1-100, integer)
- `sortDirection` 'asc' | 'desc' — Sort direction by favoritedAt (default: asc — oldest first)

## Response `200`

Paginated list of users who favorited the document

- DocumentsListFavoritesResponse
  - `pageInfo` object, required — Pagination information
    - `hasNextPage` boolean, required — Whether more results are available
    - `nextCursor` string, nullable, required — Cursor for fetching the next page
    - `pageSize` number, required — Number of results per page
    - `totalRecords` number, required — Total number of records matching the query
  - `records` DocumentFavoriteUser[], required — Users who favorited this document
    - `email` string, nullable, required — Favoriting user's email. Null when the user has no resolvable email — e.g. an embed-SSO favoriter whose embed session did not provide one.
    - `favoritedAt` string, required — ISO 8601 timestamp when the user favorited the document
    - `name` string, required — Favoriting user's display name
    - `userId` string, required — Membership ID of the user who favorited the document (use with other v1 endpoints' userId parameter)

## Other responses

- `400` — Invalid query parameters
- `401` — Authentication required
- `403` — Permission denied — caller lacks MANAGER on the document, or used a user-scoped (personal access token) API key (org-scoped only)
- `404` — Document not found

---

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