v5

OpenAPI 3.1.02026-08-025631,1012.8 MB

Documents

List documents across all collections (namespace-scoped).

List documents across all collections in the namespace.

Use this when you don't know which collection a document belongs to, or when you need to search across collections. Optionally filter to specific collection_ids.

For collection-specific listing, use POST /v1/collections/{collection_id}/documents/list instead.

post/v1/documents/list

Query parameters

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

collection_idsstring[] nullable

Optional list of collection IDs to filter by. When omitted, returns documents from all collections in the namespace.

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
  }
}