> ## Documentation Index > Fetch the complete documentation index at: https://docs.omni.co/llms.txt > Use this file to discover all available pages before exploring further. # List documents > List documents with pagination and filtering ## OpenAPI ````yaml /api/openapi.yaml get /v1/documents openapi: 3.1.0 info: title: Omni API description: > The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. version: 1.0.0 contact: name: Omni Support url: https://docs.omni.co servers: - url: https://{instance}.omniapp.co/api description: Production variables: instance: default: blobsrus description: Your production Omni instance subdomain - url: https://{instance}.playground.exploreomni.dev/api description: Playground variables: instance: default: blobsrus description: Your playground Omni instance subdomain security: - bearerAuth: [] - orgApiKey: [] tags: - name: AI description: AI-powered query generation - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Content description: Unified content retrieval (documents and folders) - name: Content migration description: Export and import dashboards - name: Content validator description: Validate content against models and perform find/replace operations - name: Dashboard downloads description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files - name: Dashboard filters and controls description: Read and update dashboard filter and control default values - name: dbt description: Manage dbt configuration for connections - name: Documents description: Create, retrieve, and manage documents - name: Document favorites description: Favorite and unfavorite documents - name: Document labels description: Apply and manage labels on documents - name: Document permissions description: Manage document-level access - name: Labels description: > Manage labels in an organization. Labels can be applied to documents and folders to help organize and categorize content. **Label types:** - **Basic labels**: Can be created and managed by any user - **Verified labels**: Indicate curated or officially sanctioned content. Admin-only. - **Homepage labels**: Appear on the organization homepage. Admin-only. - name: Folders description: Create and organize content folders - name: Folder permissions description: Manage folder-level access - name: Jobs description: Check status of asynchronous jobs - name: Models description: Create and manage data models - name: Model branches description: Manage model branches and merge changes - name: Model git configuration description: Manage git configuration for shared models - name: Queries description: Execute workbook queries - name: Schedules description: Create and manage scheduled tasks - name: Schedule recipients description: Manage schedule recipients - name: Schema refresh schedules description: Manage automated schema refresh schedules for connections - name: Topics description: Retrieve topic information from models - name: Uploads description: Manage file uploads - name: Users description: Manage users - name: User attributes description: Manage user attribute definitions - name: User groups description: Manage user groups - name: User model roles description: Manage model and connection role assignments for users - name: User group model roles description: Manage model and connection role assignments for user groups - name: Uploads description: Manage CSV and spreadsheet uploads paths: /v1/documents: get: tags: - Documents summary: List documents description: List documents with pagination and filtering operationId: listDocuments parameters: - name: include in: query schema: type: string description: > Comma-separated list of additional fields to include in the response: - `_count` - Adds favorite and view count metrics - `labels` - Includes associated document labels - `includeDeleted` - Include deleted documents - `onlyFavorites` - **Must be used with `userId`.** Include only documents that the specified user has favorited. - `onlySharedWithMe` - Returns only documents explicitly shared with the specified user via documents permissions. Excludes documents owned by the user. Cannot be combined with `ownerId` or `path`. Additionally, depending on the type of API key being used: - **Organization API keys** require the `userId` parameter - **Personal Access Tokens** automatically infer the `userId` from the token - name: labels in: query schema: type: string description: > Comma-separated list of labels to filter results. For example: `finance,marketing` - name: folderId in: query schema: type: string format: uuid description: >- ID of the folder to filter results. Returns only documents within the specified folder. - name: pageSize in: query schema: type: integer minimum: 1 maximum: 100 default: 20 description: Number of records per page - name: sortField in: query schema: type: string enum: - favorites - name - updatedAt - visits default: name description: | Field to sort by: - `favorites` - Sort by the number of favorites - `name` - Sort by document name - `updatedAt` - Sort by last update time - `visits` - Sort by view count - name: sortDirection in: query schema: type: string enum: - asc - desc default: desc description: Sort direction (`asc` for ascending, `desc` for descending) - name: cursor in: query schema: type: string description: >- Cursor for pagination. Used with `sortField`/`sortDirection` for relative positioning. - name: userId in: query schema: type: string format: uuid description: > The ID of a standard or embed user to filter results, returning only documents the specified user can view based on their permissions. If `include=onlyFavorites` is specified: - **And using an Organization API key**, this parameter is **required** - **And using a Personal Access Token**, the `userId` will be automatically inferred from the token - name: creatorId in: query schema: type: string format: uuid description: >- ID of the user who created the document(s), returning only documents that the specified user created. responses: '200': description: Paginated document list content: application/json: schema: $ref: '#/components/schemas/DocumentsListResponse' '400': description: > 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 ''` - `creatorId: Invalid uuid` - `userId: Invalid uuid` - `formErrors: Unrecognized key(s) in object: ''` - `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 content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: > Not Found Possible error messages: - `User with id 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. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/TooManyRequests' security: - bearerAuth: [] components: schemas: DocumentsListResponse: type: object properties: pageInfo: allOf: - $ref: '#/components/schemas/PageInfo' - description: Pagination information records: type: array items: $ref: '#/components/schemas/Document' description: List of documents required: - pageInfo - records Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: PageInfo: type: object description: Pagination information for paginated responses. properties: hasNextPage: type: boolean description: Indicates if there are more records available. nextCursor: type: string nullable: true description: Cursor for the next page of results. `null` if no more results. pageSize: type: integer description: Number of records per page. totalRecords: type: integer description: Total number of records matching the query. Document: type: object properties: _count: type: object properties: favorites: type: number description: Number of users who favorited this document views: type: number description: Number of views required: - favorites - views description: Document counts (included when `_count` is in `include` param) connectionId: type: string description: Connection ID the document is associated with deleted: type: boolean description: Whether the document is deleted (archived) folder: $ref: '#/components/schemas/DocumentFolder' hasDashboard: type: boolean description: Whether the document has an associated dashboard identifier: type: string description: Document identifier example: abc123 labels: type: array items: type: string description: >- Labels applied to the document (included when `labels` is in `include` param) name: type: string description: Document name description: type: string description: Description of the document owner: $ref: '#/components/schemas/DocumentOwner' scope: type: string enum: - restricted - organization description: Document access scope type: type: string enum: - document description: Content type updatedAt: type: - string - 'null' format: date-time description: Last updated timestamp url: type: string description: >- URL to view the document. Returns dashboard URL if document has a dashboard, otherwise workbook URL. example: https://org.omni.co/dashboards/abc123 required: - connectionId - deleted - folder - hasDashboard - identifier - name - owner - scope - type - updatedAt - url DocumentFolder: type: - object - 'null' description: Folder containing the document properties: id: type: string description: Folder ID name: type: string description: Folder name path: type: string description: Folder path scope: type: string enum: - restricted - organization description: Folder access scope required: - id - name - path - scope DocumentOwner: type: object description: Document owner properties: id: type: string description: Owner membership ID name: type: string description: Owner display name required: - id - name responses: TooManyRequests: description: Too Many Requests - Rate limit exceeded (60 requests/minute) content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#personal-access-tokens-pat). Include in the `Authorization` header as: `Bearer YOUR_TOKEN` orgApiKey: type: http scheme: bearer bearerFormat: JWT description: > Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint. Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY` ````