Collection Documents

List documents.

Changed on

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

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/collections/{collection_identifier}/documents
  • Auth: HTTP bearer and API key in header X-Namespace

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

Set true to count the documents that match this request. pagination.total and total_documents then hold the number of matching documents across all pages, filters included (0 when nothing matches); without it both are null. Runs a COUNT query that adds about 50-200ms. To get only the count, send limit 1. Accepted in the body or as the ?include_total=true query parameter; the 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. Vectors requested with return_vectors or return_vector_names are returned whether or not select names them, along with '_vectors'. 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"
  },
  "partition": {
    "count": 4
  },
  "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

Number of documents matching the query across all pages, filters included. null unless the request set include_total=true, so null means the count was not requested. Same value as stats.total_documents.

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

  • 2e8a69f8c920Revision changes
    • info

      added the new optional request property

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status