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

# List Docs

`POST /documents/list_docs`

Flexible document listing with aggregates, projections, and advanced pagination.

Alias: `/documents` and `/documents/list_docs` share this handler.

**Supported operators**: `$and`, `$or`, `$nor`, `$not`, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`,
`$in`, `$nin`, `$exists`, `$type`, `$regex`, `$contains`.

**Implicit equality** (backwards compatible, JSONB containment):
```json
{"status": "active"}
```

**Explicit operators** (typed comparisons for number, decimal, datetime, date):
```json
{"priority": {"$gte": 40}, "end_date": {"$lt": "2025-01-01"}}
```

Use `document_filters` with a `filename` key to filter the filename column:
```json
{"filename": {"$regex": {"pattern": "^report_.*\.pdf$", "flags": "i"}}}
```

Use `folder_name` and `end_user_id` query parameters to scope system metadata.

## Query parameters

- `folder_name` union
  - string
  - string[]
- `folder_depth` integer, nullable — Folder scope depth: 0/None = exact, -1 = all descendants, n > 0 = include descendants up to n levels.
- `end_user_id` string, nullable

## Headers

- `authorization` string, nullable

## Request body

- ListDocsRequest — Flexible request model for listing documents with projection and aggregates.
  - `document_filters` object, nullable — Metadata filters with operator support: $and, $or, $nor, $not, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $type, $regex, $contains. Implicit equality uses JSONB containment; explicit operators support typed comparisons. Reserved key: 'filename' filters the filename column.
  - `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). Derived fields such as 'page_count' are also 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

---

[API](https://skmtc.net/morphik-org/apis/fastapi.md) · [All operations](https://skmtc.net/morphik-org/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/morphik-org/fastapi/versions/2d9291c3821d/schema)