v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB

Collection Documents

List documents.

List documents with optional grouping support.

Supports two modes:

Regular listing: Returns flat list of documents with pagination
Grouped listing: When group_by is specified, returns documents grouped by field value

When using group_by:

Requires a payload index on the specified field in Qdrant
Pagination applies to groups, not individual documents
Each group contains all documents sharing the same field value

post/v1/collections/{collection_identifier}/documents/list

Path parameters

collection_identifierstring required

The ID of the collection to list documents from.

Query parameters

return_presigned_urlsboolean

Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field — if either is true, presigning is enabled.

return_vectorsboolean

Include vector embeddings in results. Also accepted as a body field — if either is true, vectors are returned.

filtersstring nullable

URL-encoded JSON filter (LogicalOperator shape: {"AND":[{"field":"metadata.status","operator":"eq","value":"active"}]}; OR/NOT also supported). Applies to the GET listing. POST /documents/list callers should send filters in the JSON body instead — the body wins when both are present. Invalid JSON returns 422 (never silently ignored).

searchstring nullable

Free-text search across common document fields. Body search wins when both are set.

sortstring nullable

Sort spec as JSON ({"field":"created_at","direction":"desc"}) or the compact "field:direction" form. Body sort wins when both are set.

limitinteger nullable

page_sizeinteger nullable

offsetinteger nullable

pageinteger nullable

cursorstring nullable

next_cursorstring nullable

afterstring nullable

include_totalboolean

Request body

searchstring nullable

Search term.

cursorstring nullable

OPTIONAL cursor for efficient deep pagination. Pass the 'pagination.next_cursor' value from a previous response to fetch the next page. When cursor is provided, the page/offset query params are ignored. Use cursor-based pagination when: (1) paginating beyond page ~100, (2) sorting large datasets, or (3) you need consistent iteration. Use offset-based pagination (default) for: simple use cases, random page access, or when page numbers are needed in the UI.

include_totalboolean nullable

Populate pagination.total/total_pages (runs a COUNT query, adds ~50-200ms). Accepted here in the BODY as well as the ?include_total=true query param — previously only the query-param form worked and a body include_total was silently swallowed (placement-sensitivity class). Body value wins when both are set.

return_presigned_urlsboolean nullable

Whether to return presigned URLs for object keys.

return_vectorsboolean nullable

Whether to return vector embeddings in the document results.

group_bystring nullable

OPTIONAL. Field to group documents by. Supports dot notation for nested fields (e.g., 'metadata.category', 'source_type'). Accepts either a bare string ('metadata.category') or an object form ({'field': 'metadata.category'}) for consistency with other API parameters. When specified, documents are grouped by the field value and returned as grouped results. Requires a payload index on the field in Qdrant for optimal performance. If no index exists, the operation will fail with a validation error. Common groupable fields: 'source_object_id', 'root_object_id', 'collection_id', 'metadata.category'.

selectstring[] nullable

OPTIONAL. List of fields to include in the response. Supports dot notation for nested fields (e.g., 'metadata.title', 'content'). When specified, only the selected fields will be returned in the document results, reducing response size. System fields like '_id' and 'document_id' are always included. Use this to optimize response size when working with large documents.

expandstring[] nullable

OPTIONAL. List of fields containing document IDs to resolve inline. Referenced documents are fetched and attached under an '_expanded' key. Supports dot-notation for nested fields (e.g., 'items.product_id'). Max 50 unique references per request. Depth is limited to 1 (no recursive expansion).

limitinteger

Number of documents to return per page. Capped at 1000. Accepts page_size as an alias (POST body only).

offsetinteger

Number of documents to skip (offset-based pagination).

Example request

{
  "filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "sort": {
    "field": "created_at"
  },
  "group_by": "source_object_id",
  "select": [
    "metadata.title",
    "content"
  ],
  "expand": [
    "customer_id"
  ]
}

Response

Successful Response

unknown_collection_idsstring[] nullable

Requested collection_ids that do NOT exist in this namespace. Present only on the namespace-scoped list when SOME requested ids resolved and others did not — so a typo'd or deleted collection id is distinguishable from a real-but-empty collection instead of silently contributing zero results forever. When NONE of the requested ids resolve, the endpoint returns 404 instead.

total_documentsinteger nullable

Total number of documents matching the query (across all pages). Alias for stats.total_documents — included at the top level for convenience.

group_by_fieldstring nullable

The field that was used for grouping when group_by was specified. None for non-grouped results. Useful for clients to understand the grouping structure.

Example response

{
  "description": "Regular document list (no grouping)",
  "pagination": {
    "has_more": false,
    "limit": 10,
    "offset": 0,
    "total_count": 1
  },
  "results": [
    {
      "collection_id": "col_articles",
      "document_id": "doc_123",
      "metadata": {
        "title": "AI Article"
      }
    }
  ],
  "stats": {
    "avg_blobs_per_document": 1,
    "total_documents": 1
  }
}