---
title: "List Docs"
method: POST
path: "/documents/list_docs"
tags: ["Documents"]
---

# List Docs

`POST /documents/list_docs`

Flexible document listing endpoint with support for aggregates, projections, and advanced pagination.

`request.document_filters` supports equality plus `$and`, `$or`, `$nor`, `$not`, `$in`, `$nin`, `$exists`,
`$regex`, and `$contains`, with arbitrary nesting. Scalar comparisons match array elements automatically.
Example:

```json
{
  "$and": [
    {"category": "patent"},
    {"$nor": [{"status": "archived"}, {"priority": {"$in": ["low", "medium"]}}]}
  ]
}
```

Use the `folder_name` and `end_user_id` query parameters to scope system metadata instead of embedding those
keys in the filter payload.

## Query parameters

- `folder_name` union
  - string
  - string[]
- `end_user_id` string, nullable

## Headers

- `authorization` string

## Request body

- ListDocsRequest — Flexible request model for listing documents with projection and aggregates.
  - `document_filters` object, nullable — Metadata filters for documents
  - `skip` integer — Number of documents to skip
  - `limit` integer — Maximum number of documents to return
  - `return_documents` boolean — When false, only aggregates are returned
  - `include_total_count` boolean — Include total number of matching documents when true
  - `include_status_counts` boolean — Include document counts grouped by processing status when true
  - `include_folder_counts` boolean — Include document counts grouped by folder when true
  - `completed_only` boolean — When true, only documents with completed processing status are returned and counted
  - `sort_by` 'created_at' | 'updated_at' | 'filename' | 'external_id', nullable — Field to sort the results by
  - `sort_direction` 'asc' | 'desc' — Sort direction for the results
  - `fields` string[], nullable — Optional list of fields to project for each document (dot notation supported)

## Response `200`

Successful Response

- ListDocsResponse — Flexible response for listing documents with aggregates.
  - `documents` unknown[]
    - unknown
  - `skip` integer, required
  - `limit` integer, required
  - `returned_count` integer, required
  - `total_count` integer, nullable
  - `has_more` boolean
  - `next_skip` integer, nullable
  - `status_counts` object, nullable
  - `folder_counts` FolderCount[], nullable
    - `folder` string, nullable, required
    - `count` integer, required

## Other responses

- `422` — Validation Error

## Changes

- **2025-11-05** `9ade02dd7b1d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/morphik-org/apis/fastapi/changes/documents/list_docs/post.md)

---

[API](https://skmtc.dev/morphik-org/apis/fastapi.md) · [All operations](https://skmtc.dev/morphik-org/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/morphik-org/fastapi/revisions/9ade02dd7b1d/schema)