Sign in
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.

warningsstring[] nullable

Result-shape warnings the caller must not ignore (BACKE-3035). Present when the listing is silently incomplete — e.g. a sorted listing scanned only the first 10,000 matching points, so the sort ranks a truncated subset and pagination ends at the cap rather than the end of the collection. Absent when the result is complete.

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

Changes

Changed in 5 of the 28 revisions of this API.214

  • 1c7f318214242See the full diff
    • ●

      added the new signal enum value to the groups/anyOf[subschema #1]/items/documents/items/_internal/anyOf[subschema #1: InternalPayloadModel]/lineage/anyOf[subschema #1: InternalLineageModel]/source_type/anyOf[subschema #1]/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new signal enum value to the results/anyOf[subschema #1]/items/_internal/anyOf[subschema #1: InternalPayloadModel]/lineage/anyOf[subschema #1: InternalLineageModel]/source_type/anyOf[subschema #1]/ response property for the response status 200

      response-property-enum-value-added

  • 5d4c905106b41See the full diff
    • ○

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API

      api-security-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9603dfdab4631See the full diff
    • ○

      added the optional property warnings to the response with the 200 status

      response-optional-property-added

  • 72cc17ba6f7f2See the full diff
    • ○

      added the new optional query request parameter after

      new-optional-request-parameter

    • ○

      added the new optional query request parameter next_cursor

      new-optional-request-parameter

  • 7cb05153331110See the full diff
    • ○

      added the new optional request property include_total

      new-optional-request-property

    • ○

      added the new geo_bounding_box enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/AND/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_bounding_box enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/NOT/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_bounding_box enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/OR/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/AND/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/NOT/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/OR/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/AND/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/NOT/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/OR/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog