---
title: "List documents"
method: GET
path: "/v1/documents"
tags: ["Documents"]
---

# List documents

`GET /v1/documents`

List documents with pagination and filtering

## Query parameters

- `include` string
- `labels` string
- `folderId` string, uuid
- `pageSize` integer
- `sortField` 'favorites' | 'name' | 'updatedAt' | 'visits'
- `sortDirection` 'asc' | 'desc'
- `cursor` string
- `userId` string, uuid
- `creatorId` string, uuid

## Response `200`

Paginated document list

- DocumentsListResponse
  - `pageInfo` object, required — Pagination information
    - `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` Document[], required — List of documents
    - `_count` object — Document counts (included when `_count` is in `include` param)
      - `favorites` number, required — Number of users who favorited this document
      - `views` number, required — Number of views
    - `connectionId` string, required — Connection ID the document is associated with
    - `deleted` boolean, required — Whether the document is deleted (archived)
    - `folder` DocumentFolder, nullable, required — Folder containing the document
      - `id` string, required — Folder ID
      - `name` string, required — Folder name
      - `path` string, required — Folder path
      - `scope` 'restricted' | 'organization', required — Folder access scope
    - `hasDashboard` boolean, required — Whether the document has an associated dashboard
    - `identifier` string, required — Document identifier
    - `labels` string[] — Labels applied to the document (included when `labels` is in `include` param)
    - `name` string, required — Document name
    - `description` string — Description of the document
    - `owner` DocumentOwner, required — Document owner
      - `id` string, required — Owner membership ID
      - `name` string, required — Owner display name
    - `scope` 'restricted' | 'organization', required — Document access scope
    - `type` 'document', required — Content type
    - `updatedAt` string, date-time, nullable, required — Last updated timestamp
    - `url` string, required — URL to view the document. Returns dashboard URL if document has a dashboard, otherwise workbook URL.

## Other responses

- `400` — Bad Request Possible error messages: - `pageSize: Page size must be at least 1` - `pageSize: Page size cannot exceed 100` - `sortField: Invalid enum value. Expected 'favorites' | 'name' | 'updatedAt' | 'visits', received '<invalidField>'` - `creatorId: Invalid uuid` - `userId: Invalid uuid` - `formErrors: Unrecognized key(s) in object: '<unknownParameter>'` - `onlySharedWithMe requires userId` - When using `include=onlySharedWithMe` without providing a `userId` parameter - `onlySharedWithMe cannot be combined with onlyFavorites` - When using both `include=onlySharedWithMe` and `include=onlyFavorites` together - `onlySharedWithMe cannot be combined with folderId` - When using `include=onlySharedWithMe` with a `folderId` parameter
- `404` — Not Found Possible error messages: - `User with id <uuid> does not exist` **Note**: An invalid UUID format will result in a 400 error. This 404 error occurs when the provided ID is a valid UUID format but the user cannot be found.
- `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)