---
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, nested logic operators, `$regex`, `$contains`,
etc.), 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.

Args:
    request: RetrieveRequest containing query parameters, metadata filters, and padding instructions
    auth: Authentication context

Returns:
    GroupedChunkResponse: Contains both flat chunks and grouped 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

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