Sign in
Collection Documents

List documents.

List documents with optional grouping support.

Supports two modes:

  1. Regular listing: Returns flat list of documents with pagination
  2. 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 the vector store
  • Pagination applies to groups, not individual documents
  • Each group contains all documents sharing the same field value
get/v1/collections/{collection_identifier}/documents

Path parameters

collection_identifierstring required

The ID of the collection to list documents from.

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.

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.

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

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.

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.

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 the vector store 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.

warningsstring[] nullable

Result-shape warnings the caller must not ignore. 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 34 revisions of this API.214

  • 1c7f318214242See the full diff
    • ●

      added the new signal enum value to the ////////// response property for the response status

      response-property-enum-value-added

    • ●

      added the new signal enum value to the //////// response property for the response status

      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 to the response with the 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

      new-optional-request-property

    • ○

      added the new geo_bounding_box enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_bounding_box enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_bounding_box enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property //////

      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