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

List documents.

cURL

curl --request GET \
  --url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "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",
    "direction": "desc"
  },
  "search": "<string>",
  "cursor": "<string>",
  "partition": {
    "count": 4,
    "index": 0
  },
  "include_total": true,
  "return_presigned_urls": false,
  "return_vectors": false,
  "return_vector_names": false,
  "group_by": "source_object_id",
  "select": [
    "metadata.title",
    "content"
  ],
  "expand": [
    "customer_id"
  ],
  "limit": 10,
  "offset": 0
}
'

200

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

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

collection_identifier · string · required

The ID of the collection to list documents from.

Query Parameters

return_presigned_urls · boolean · default: false

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_vectors · boolean · default: false

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

filters · string | null

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

search · string | null

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

sort · string | null

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

limit · integer | null

Required range: 1 <= x <= 1000

page_size · integer | null

Required range: 1 <= x <= 1000

offset · integer | null

Required range: 0 <= x <= 10000

page · integer | null

Required range: x >= 1

cursor · string | null

next_cursor · string | null

after · string | null

include_total · boolean · default: false

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request model for listing documents.

Supports two pagination strategies:

Offset-based (default): Use query params ?page=2&page_size=10

• Simple and familiar
• Works well for shallow pagination (first ~100 pages)
• Less efficient for deep pagination with sorting

Cursor-based (optional): Pass cursor from previous response's next_cursor

• More efficient for deep pagination (page 100+)
• Required for consistent results when sorting large datasets
• When cursor is provided, offset is ignored

filters · LogicalOperator · object | null

Filters to apply.

Show child attributes

sort · SortOption · object | null

Sort options.

Show child attributes

search · string | null

Search term.

cursor · string | null

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.

partition · ListPartition · object | null

OPTIONAL. Read one of count disjoint partitions of the matching documents, so several workers can page through a large collection in parallel, each with its own cursor and with no offset cap. The documents are split on their document id and every document falls in exactly one partition. Page each partition with its pagination.next_cursor until that is null; the cursor carries its partition, so sending the cursor alone stays inside it. Example: four workers send {"index": 0, "count": 4} through {"index": 3, "count": 4}. The split points are even over Mixpeek-generated document ids (doc_ followed by hex). Documents written with your own document_id values can all fall in one partition, which can be slower than one sequential listing; to split those, give each worker a range filter on document_id instead.

Show child attributes

Example:

{ "count": 4, "index": 0 }

include_total · boolean | null

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, or with a warning if the count fails, 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_urls · boolean | null · default: false

Whether to return presigned URLs for object keys.

return_vectors · boolean | null · default: false

Whether to return vector embeddings in the document results.

return_vector_names · boolean string[] · default: false

Controls vector data in the response. Pass true to get a _vectors field listing available vector names (no embedding data). Pass a list of vector names (e.g. ["fashionsiglip_v1_embedding"]) to return the actual float arrays for those specific vectors, keyed by name.

group_by · string | null

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

Example:

"source_object_id"

select · string[] | null

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.

Example:

["metadata.title", "content"]

expand · string[] | null

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

Example:

["customer_id"]

limit · integer · default: 10

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

Required range: 1 <= x <= 1000

offset · integer · default: 0

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

Required range: x >= 0

Response

200

application/json

Successful Response

Response model for listing documents.

Supports both regular document lists and grouped results based on the group_by parameter. When group_by is specified, results are returned as groups instead of a flat list.

Pagination strategies:

• Offset-based (default): Use pagination.page and pagination.page_size
• Cursor-based (optional): Use pagination.next_cursor for efficient deep pagination

pagination · PaginationResponse · object · required

Pagination information. Includes next_cursor for cursor-based pagination. pagination.total is the number of matching documents when the request sets include_total=true, and null otherwise. When group_by is used, pagination applies to groups (not individual documents) and pagination.total counts groups.

Show child attributes

results · DocumentResponse · object[] | null

List of documents when group_by is NOT specified. Contains flat list of documents with pagination applied. Mutually exclusive with 'groups' field.

Show child attributes

groups · DocumentGroup · object[] | null

List of document groups when group_by IS specified. Each group contains documents sharing the same field value. Pagination applies to groups, not individual documents. Mutually exclusive with 'results' field.

Show child attributes

unknown_collection_ids · string[] | null

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.

warnings · string[] | null

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_documents · integer | null

Number of documents matching the query across all pages, filters included. null unless the request set include_total=true. A request that set it gets null only when the count could not be computed, and warnings then says so. Same value as stats.total_documents.

stats · DocumentListStats · object | null

Aggregate statistics across all documents in the result

Show child attributes

group_by_field · string | null

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:

"source_object_id"