---
title: "Retrieve Chunks"
method: POST
path: "/retrieve/chunks"
---

# Retrieve Chunks

`POST /retrieve/chunks`

Retrieve relevant chunks.

The optional `request.filters` payload accepts equality checks (automatically matching scalars inside JSON
arrays) plus the operators `$and`, `$or`, `$nor`, `$not`, `$in`, `$nin`, `$exists`, `$regex`, and `$contains`.
Regex filters allow the optional `i` flag for case-insensitive matching, while `$contains` performs substring
checks (case-insensitive by default, configurable via `case_sensitive`). Filters can be nested freely, for
example:

```json
{
  "$and": [
    {"category": "policy"},
    {"$or": [{"region": "emea"}, {"priority": {"$in": ["p0", "p1"]}}]}
  ]
}
```

Args:
    request: RetrieveRequest containing:
        - query: Search query text
        - filters: Optional metadata filters
        - k: Number of results (default: 4)
        - min_score: Minimum similarity threshold (default: 0.0)
        - use_reranking: Whether to use reranking
        - use_colpali: Whether to use ColPali-style embedding model
        - folder_name: Optional folder to scope the search to
        - end_user_id: Optional end-user ID to scope the search to
    auth: Authentication context

Returns:
    List[ChunkResult]: List of relevant chunks

## Headers

- `authorization` string

## Request body

- RetrieveRequest — Base retrieve request model
  - `query` string, required
  - `filters` object, nullable
  - `k` integer
  - `min_score` number
  - `use_reranking` boolean, nullable
  - `use_colpali` boolean, nullable
  - `padding` integer — Number of additional chunks/pages to retrieve before and after matched chunks (ColPali only)
  - `graph_name` string, nullable — Name of the graph to use for knowledge graph-enhanced retrieval
  - `hop_depth` integer, nullable — Number of relationship hops to traverse in the graph
  - `include_paths` boolean, nullable — Whether to include relationship paths in the response
  - `folder_name` union — Optional folder scope for the operation. Accepts a single folder name or a list of folder names.
    - string
    - string[]
  - `end_user_id` string, nullable — Optional end-user scope for the operation

## Response `200`

Successful Response

- ChunkResult[]
  - `content` string, required
  - `score` number, required
  - `document_id` string, required
  - `chunk_number` integer, required
  - `metadata` object, required
  - `content_type` string, required
  - `filename` string, nullable
  - `download_url` string, nullable
  - `is_padding` boolean — Whether this chunk was added as padding

## Other responses

- `422` — Validation Error

---

[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)