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

# Retrieve Chunks Grouped

`POST /retrieve/chunks/grouped`

Retrieve relevant chunks with grouped response format.

Uses the same filter operators as `/retrieve/chunks` (equality, `$eq/$ne`, `$gt/$gte/$lt/$lte`, `$in/$nin`,
`$exists`, `$type`, `$regex`, `$contains`, and the logical `$and/$or/$nor/$not`), with arbitrary nesting
supported inside `request.filters`.

Returns both flat results (for backward compatibility) and grouped results (for UI).
When padding > 0, groups chunks by main matches and their padding chunks.

## Headers

- `authorization` string, nullable

## Request body

- RetrieveRequest — Base retrieve request model
  - `query` string, nullable — Natural-language query used to retrieve relevant chunks or documents.
  - `query_image` string, nullable — Base64-encoded image to use as query for Morphik multimodal retrieval. Requires use_colpali=True. Mutually exclusive with 'query'.
  - `filters` object, nullable — Metadata filters supporting logical operators ($and/$or/$not/$nor) and field predicates ($eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$exists/$type/$regex/$contains).
  - `k` integer — Maximum number of chunks or documents to return.
  - `min_score` number — Minimum similarity score a result must meet before it is returned.
  - `use_reranking` boolean, nullable — When provided, overrides the workspace reranking configuration for this request.
  - `use_colpali` boolean, nullable — When provided, uses Morphik's finetuned ColPali style embeddings (recommended to be True for high quality retrieval).
  - `output_format` 'base64' | 'url' | 'text' — Output format for image chunks in retrieval results.
  - `padding` integer — Number of additional chunks/pages to retrieve before and after matched chunks (ColPali only)
  - `folder_name` union — Optional folder scope. Accepts a folder PATH (e.g., '/Company/Reports') or list of paths.
    - string
    - string[]
  - `folder_depth` integer, nullable — Folder scope depth. 0 or None = exact folder only, -1 = include all descendants, n > 0 = include descendants up to n levels deeper.
  - `end_user_id` string, nullable — Optional end-user scope for the operation

## Response `200`

Successful Response

- GroupedChunkResponse — Response that includes both flat results and grouped results for UI
  - `chunks` ChunkResult[], required — Flat list of all chunks (for backward compatibility)
    - `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
  - `groups` ChunkGroup[], required — Grouped chunks for UI display
    - `main_chunk` ChunkResult, required — Query result at chunk level
      - `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
    - `padding_chunks` 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
    - `total_chunks` integer, required — Total number of chunks in this group
  - `total_results` integer, required — Total number of unique chunks
  - `has_padding` boolean, required — Whether padding was applied to any results

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