Skip to main content
POST
/
v1
/
collections
/
{collection_identifier}
/
documents
/
list
List documents.
curl --request POST \
  --url https://api.mixpeek.com/v1/collections/{collection_identifier}/documents/list \
  --header 'Content-Type: application/json' \
  --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>",
  "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
}
'
{
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>",
    "next_cursor": "<string>"
  },
  "results": [
    {
      "document_id": "<string>",
      "collection_id": "<string>",
      "document_blobs": [
        {
          "field": "<string>",
          "url": "<string>",
          "role": "source",
          "type": "other",
          "filename": "segment_0.mp4",
          "size_bytes": 1048576,
          "content_type": "video/mp4",
          "checksum": "sha256:a1b2c3d4e5f6...",
          "created_at": "2023-11-07T05:31:56Z",
          "source_blob_id": "blob_abc123",
          "presigned_url": "<string>"
        }
      ],
      "_internal": {
        "collection_id": "col_articles",
        "created_at": "2025-10-31T10:00:00Z",
        "document_id": "doc_f8966ff29c",
        "internal_id": "org_abc123",
        "lineage": {
          "path": "bkt_content/col_articles",
          "root_bucket_id": "bkt_content",
          "root_object_id": "obj_article_001",
          "source_object_id": "obj_article_001",
          "source_type": "bucket"
        },
        "metadata": {
          "ingestion_status": "COMPLETED"
        },
        "modality": "text",
        "namespace_id": "ns_xyz789",
        "updated_at": "2025-10-31T10:00:00Z"
      }
    }
  ],
  "groups": [
    {
      "group_key": "<unknown>",
      "documents": [
        {
          "document_id": "<string>",
          "collection_id": "<string>",
          "document_blobs": [
            {
              "field": "<string>",
              "url": "<string>",
              "role": "source",
              "type": "other",
              "filename": "segment_0.mp4",
              "size_bytes": 1048576,
              "content_type": "video/mp4",
              "checksum": "sha256:a1b2c3d4e5f6...",
              "created_at": "2023-11-07T05:31:56Z",
              "source_blob_id": "blob_abc123",
              "presigned_url": "<string>"
            }
          ],
          "_internal": {
            "collection_id": "col_articles",
            "created_at": "2025-10-31T10:00:00Z",
            "document_id": "doc_f8966ff29c",
            "internal_id": "org_abc123",
            "lineage": {
              "path": "bkt_content/col_articles",
              "root_bucket_id": "bkt_content",
              "root_object_id": "obj_article_001",
              "source_object_id": "obj_article_001",
              "source_type": "bucket"
            },
            "metadata": {
              "ingestion_status": "COMPLETED"
            },
            "modality": "text",
            "namespace_id": "ns_xyz789",
            "updated_at": "2025-10-31T10:00:00Z"
          }
        }
      ],
      "count": 123
    }
  ],
  "total_documents": 123,
  "stats": {
    "total_documents": 0,
    "avg_blobs_per_document": 0,
    "total_groups": 123,
    "avg_documents_per_group": 123
  },
  "group_by_field": "source_object_id"
}

Headers

​
Authorization
string

Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Example:

"Bearer YOUR_MIXPEEK_API_KEY"

​
authorization
string
​
X-Namespace
string

Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'. Falls back to ?namespace= query parameter if the header is omitted.

Examples:

"ns_abc123def456"

"production"

"my-namespace"

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.

​
limit
integer | null
Required range: 1 <= x <= 1000
​
offset
integer | null
Required range: 0 <= x <= 10000
​
cursor
string | null
​
include_total
boolean
default:false

Body

application/json

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

Filters to apply.

​
sort
SortOption · object

Sort options.

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

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

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

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. When group_by is used, pagination applies to groups (not individual documents). total_count reflects total number of groups, not total documents.

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

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

​
total_documents
integer | null

Total number of documents matching the query (across all pages). Alias for stats.total_documents — included at the top level for convenience.

​
stats
DocumentListStats · object

Aggregate statistics across all documents in the result

​
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"