--- title: "List documents." method: GET path: "/v1/collections/{collection_identifier}/documents" tags: ["Collection Documents"] --- # List documents. `GET /v1/collections/{collection_identifier}/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 Qdrant - Pagination applies to groups, not individual documents - Each group contains all documents sharing the same field value ## Path parameters - `collection_identifier` string, required — The ID of the collection to list documents from. ## Query parameters - `return_presigned_urls` boolean — 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 — Include vector embeddings in results. Also accepted as a body field — if either is true, vectors are returned. - `filters` string, 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). - `search` string, nullable — Free-text search across common document fields. Body `search` wins when both are set. - `sort` string, nullable — Sort spec as JSON ({"field":"created_at","direction":"desc"}) or the compact "field:direction" form. Body `sort` wins when both are set. - `limit` integer, nullable - `page_size` integer, nullable - `offset` integer, nullable - `page` integer, nullable - `cursor` string, nullable - `next_cursor` string, nullable - `after` string, nullable - `include_total` boolean ## Request body - ListDocumentsRequest — 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` LogicalOperatorInput — Represents a logical operation (AND, OR, NOT) on filter conditions. Allows nesting with a defined depth limit. Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}). - `AND` union[], nullable — Logical AND operation - all conditions must be true - union - LogicalOperatorInput — recursive - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required — Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `value` union, required — Value to compare against - DynamicValue — A value that should be dynamically resolved from the query request. - … - unknown - `OR` union[], nullable — Logical OR operation - at least one condition must be true - union - LogicalOperatorInput — recursive - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required — Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `value` union, required — Value to compare against - DynamicValue — A value that should be dynamically resolved from the query request. - … - unknown - `NOT` union[], nullable — Logical NOT operation - all conditions must be false - union - LogicalOperatorInput — recursive - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required — Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `value` union, required — Value to compare against - DynamicValue — A value that should be dynamically resolved from the query request. - … - unknown - `case_sensitive` boolean, nullable — Whether to perform case-sensitive matching - `sort` SortOption — Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending) - `field` string, required — Field to sort by, supports dot notation for nested fields - `direction` 'asc' | 'desc' — Sort direction options. - `search` string, nullable — Search term. - `cursor` string, 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_total` boolean, 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_urls` boolean, nullable — Whether to return presigned URLs for object keys. - `return_vectors` boolean, nullable — Whether to return vector embeddings in the document results. - `return_vector_names` union — 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. - boolean - string[] - `group_by` string, 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'. - `select` string[], 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. - `expand` string[], 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). - `limit` integer — Number of documents to return per page. Capped at 1000. Accepts ``page_size`` as an alias (POST body only). - `offset` integer — Number of documents to skip (offset-based pagination). ## Response `200` Successful Response - ListDocumentsResponse — 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 - `results` DocumentResponse[], nullable — List of documents when group_by is NOT specified. Contains flat list of documents with pagination applied. Mutually exclusive with 'groups' field. - `document_id` string, required — REQUIRED. Unique identifier for the document. Format: 'doc_' prefix + alphanumeric characters. Use for: API queries, references, filtering. - `collection_id` string, required — REQUIRED. ID of the collection this document belongs to. Format: 'col_' prefix + alphanumeric characters. Use for: Collection-scoped queries, filtering. - `document_blobs` BlobURLRef[] — Document blobs with presigned URLs when requested - `field` string, required — REQUIRED. Stable semantic label for this blob. Use descriptive names like 'video_segment', 'thumbnail', 'source_video', etc. Avoid internal implementation details like array indices. This field is used for programmatic access and should be consistent across documents. - `role` 'source' | 'processed' | 'thumbnail' | 'artifact' | 'aux' — REQUIRED. Semantic role determining how this blob should be treated. 'source': Original input media from buckets or uploads. 'processed': Derived content created by feature extractors (segments, frames). 'thumbnail': Preview images for UI display. 'artifact': Generated outputs (reports, analysis results). 'aux': Supporting or auxiliary files. Used by UI for grouping and displaying blobs appropriately. - `type` 'video' | 'image' | 'audio' | 'text' | 'pdf' | 'other' — REQUIRED. Media type of the blob content. Determines how the blob should be rendered or processed. Use 'other' for custom or unknown types. - `url` string, required — REQUIRED. Permanent URL to the blob content. S3 URLs (s3://bucket/key) are automatically converted to presigned HTTPS URLs by the API. HTTP/HTTPS URLs are returned as-is. This is the canonical reference to the blob that persists across API calls. - `filename` string, nullable — OPTIONAL. Original filename or leaf name of the blob. Useful for downloads and display purposes. Example: 'segment_0.mp4', 'thumbnail.jpg' - `size_bytes` integer, nullable — OPTIONAL. Size of the blob in bytes. Useful for progress indicators and storage tracking. - `content_type` string, nullable — OPTIONAL. MIME type of the blob content. Used for proper content-type headers when serving files. Example: 'video/mp4', 'image/jpeg', 'application/pdf' - `checksum` string, nullable — OPTIONAL. Checksum or hash of the blob content for integrity verification. Format: 'algorithm:hash' (e.g., 'sha256:abc123...') - `created_at` string, date-time, nullable — OPTIONAL. Timestamp when the blob was created or uploaded. ISO 8601 format. Useful for tracking blob lifecycle and cleanup. - `source_blob_id` string, nullable — OPTIONAL. Cross-reference to the source blob ID from the bucket object. Used for lineage tracking: connects processed blobs back to their original sources. Example: A video segment references the original video blob that it was extracted from. - `presigned_url` string, uri, nullable — RESPONSE ONLY. Time-limited HTTPS URL for direct access to the blob. Automatically generated by the API when documents are retrieved. NOT REQUIRED when creating blobs - leave empty, API will populate. Typically expires after 1 hour. Use for immediate media playback or download. - `_internal` InternalPayloadModel — Complete _internal field structure for Qdrant document payloads. All Mixpeek-managed system fields are namespaced under this structure to: - Prevent collision with user-defined fields - Provide clear separation of system vs user data - Enable filtering on internal fields via _internal.field_name paths This structure is stored in Qdrant and returned in API responses. - `internal_id` string, nullable — Organization/tenant identifier for multi-tenancy isolation. - `namespace_id` string, nullable — Namespace identifier within the organization. - `document_id` string, nullable — Document identifier (also at root level for convenience). - `collection_id` string, nullable — Collection identifier (also at root level for convenience). - `created_at` string, nullable — ISO 8601 timestamp when document was created. - `updated_at` string, nullable — ISO 8601 timestamp when document was last updated. - `lineage` InternalLineageModel — Lineage tracking information for document provenance. Tracks the complete processing history from the original bucket object through all transformation stages in the decomposition tree. - `root_object_id` string, nullable — Original object ID from bucket (root of decomposition tree). All documents derived from the same object share this ID. - `root_bucket_id` string, nullable — Bucket ID containing the root object. - `source_type` 'bucket' | 'collection' | 'direct_upsert', nullable — Type of immediate parent source. 'bucket': Document created directly from bucket object (tier 1). 'collection': Document created from another collection (tier 2+). - `source_object_id` string, nullable — Object ID of immediate parent when source_type='bucket'. - `source_document_id` string, nullable — Document ID of immediate parent when source_type='collection'. - `source_collection_id` string, nullable — Collection ID of immediate parent when source_type='collection'. - `path` string, nullable — Materialized lineage path string (e.g., 'bkt_123/col_456/col_789'). - `chain` object[], nullable — Ordered list of processing steps from root object to this document. Each step contains: collection_id, feature_extractor_id, document_id, timestamp. - `processing` InternalProcessingModel — Processing and provenance tracking information. Consolidates all processing-related metadata including source URLs, processing history, and taxonomy enrichment lineage. - `source_url` string, nullable — Original URL before S3 mirroring (for URL-based ingestion). - `object_key_source` string, nullable — S3 key source identifier. - `detected_mime_type` string, nullable — MIME type detected during canonicalization. - `history` object[], nullable — Processing steps history with timestamps and operations. - `taxonomy_lineage` object[], nullable — Taxonomy enrichment entries applied to this document. - `last_health_check` object, nullable — Last health check result (for batch processing). - `source_blobs` object[], nullable — Blobs that constituted the original source object. - `document_blobs` object[], nullable — Blobs generated during document processing (thumbnails, etc.). - `source_details` object[], nullable — Enrichment tracking and source detail entries. - `modality` string, nullable — Content modality (text, image, video, audio, etc.). - `metadata` object, nullable — System metadata including ingestion_status, feature_extractor_config_hash, and other processing-related information. - `mime_type` string, nullable — MIME type of the source content. - `size_bytes` integer, nullable — Size of the source content in bytes. - `content_hash` string, nullable — SHA256 hash of the source content for deduplication. - `_acl` InternalACLModel — Access control list for document-level security (row-level security). Controls which end-user principals can read/write a document. Used with user-scoped API keys (keys with principal_id set). Org-scoped keys bypass ACL entirely. - `owner` string, nullable — Principal ID of the document owner (the creator). - `read` string[], nullable — List of principal IDs that can read this document. - `write` string[], nullable — List of principal IDs that can write/update this document. - `public` boolean, nullable — If true, any user-scoped key can read this document. - `groups` DocumentGroup[], nullable — 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. - `group_key` string, required — The value that documents in this group share for the group_by field. Can be string, number, boolean, or null depending on the field type. Examples: 'obj_video123' (for source_object_id), 'Electronics' (for metadata.category). - `documents` DocumentResponse[], required — List of documents that share the same group_key value. Documents within each group are sorted by relevance/score if applicable. Each document contains full document data including metadata, lineage, and blobs. - `document_id` string, required — REQUIRED. Unique identifier for the document. Format: 'doc_' prefix + alphanumeric characters. Use for: API queries, references, filtering. - `collection_id` string, required — REQUIRED. ID of the collection this document belongs to. Format: 'col_' prefix + alphanumeric characters. Use for: Collection-scoped queries, filtering. - `document_blobs` BlobURLRef[] — Document blobs with presigned URLs when requested - `field` string, required — REQUIRED. Stable semantic label for this blob. Use descriptive names like 'video_segment', 'thumbnail', 'source_video', etc. Avoid internal implementation details like array indices. This field is used for programmatic access and should be consistent across documents. - `role` 'source' | 'processed' | 'thumbnail' | 'artifact' | 'aux' — REQUIRED. Semantic role determining how this blob should be treated. 'source': Original input media from buckets or uploads. 'processed': Derived content created by feature extractors (segments, frames). 'thumbnail': Preview images for UI display. 'artifact': Generated outputs (reports, analysis results). 'aux': Supporting or auxiliary files. Used by UI for grouping and displaying blobs appropriately. - `type` 'video' | 'image' | 'audio' | 'text' | 'pdf' | 'other' — REQUIRED. Media type of the blob content. Determines how the blob should be rendered or processed. Use 'other' for custom or unknown types. - `url` string, required — REQUIRED. Permanent URL to the blob content. S3 URLs (s3://bucket/key) are automatically converted to presigned HTTPS URLs by the API. HTTP/HTTPS URLs are returned as-is. This is the canonical reference to the blob that persists across API calls. - `filename` string, nullable — OPTIONAL. Original filename or leaf name of the blob. Useful for downloads and display purposes. Example: 'segment_0.mp4', 'thumbnail.jpg' - `size_bytes` integer, nullable — OPTIONAL. Size of the blob in bytes. Useful for progress indicators and storage tracking. - `content_type` string, nullable — OPTIONAL. MIME type of the blob content. Used for proper content-type headers when serving files. Example: 'video/mp4', 'image/jpeg', 'application/pdf' - `checksum` string, nullable — OPTIONAL. Checksum or hash of the blob content for integrity verification. Format: 'algorithm:hash' (e.g., 'sha256:abc123...') - `created_at` string, date-time, nullable — OPTIONAL. Timestamp when the blob was created or uploaded. ISO 8601 format. Useful for tracking blob lifecycle and cleanup. - `source_blob_id` string, nullable — OPTIONAL. Cross-reference to the source blob ID from the bucket object. Used for lineage tracking: connects processed blobs back to their original sources. Example: A video segment references the original video blob that it was extracted from. - `presigned_url` string, uri, nullable — RESPONSE ONLY. Time-limited HTTPS URL for direct access to the blob. Automatically generated by the API when documents are retrieved. NOT REQUIRED when creating blobs - leave empty, API will populate. Typically expires after 1 hour. Use for immediate media playback or download. - `_internal` InternalPayloadModel — Complete _internal field structure for Qdrant document payloads. All Mixpeek-managed system fields are namespaced under this structure to: - Prevent collision with user-defined fields - Provide clear separation of system vs user data - Enable filtering on internal fields via _internal.field_name paths This structure is stored in Qdrant and returned in API responses. - `internal_id` string, nullable — Organization/tenant identifier for multi-tenancy isolation. - `namespace_id` string, nullable — Namespace identifier within the organization. - `document_id` string, nullable — Document identifier (also at root level for convenience). - `collection_id` string, nullable — Collection identifier (also at root level for convenience). - `created_at` string, nullable — ISO 8601 timestamp when document was created. - `updated_at` string, nullable — ISO 8601 timestamp when document was last updated. - `lineage` InternalLineageModel — Lineage tracking information for document provenance. Tracks the complete processing history from the original bucket object through all transformation stages in the decomposition tree. - `root_object_id` string, nullable — Original object ID from bucket (root of decomposition tree). All documents derived from the same object share this ID. - `root_bucket_id` string, nullable — Bucket ID containing the root object. - `source_type` 'bucket' | 'collection' | 'direct_upsert', nullable — Type of immediate parent source. 'bucket': Document created directly from bucket object (tier 1). 'collection': Document created from another collection (tier 2+). - `source_object_id` string, nullable — Object ID of immediate parent when source_type='bucket'. - `source_document_id` string, nullable — Document ID of immediate parent when source_type='collection'. - `source_collection_id` string, nullable — Collection ID of immediate parent when source_type='collection'. - `path` string, nullable — Materialized lineage path string (e.g., 'bkt_123/col_456/col_789'). - `chain` object[], nullable — Ordered list of processing steps from root object to this document. Each step contains: collection_id, feature_extractor_id, document_id, timestamp. - `processing` InternalProcessingModel — Processing and provenance tracking information. Consolidates all processing-related metadata including source URLs, processing history, and taxonomy enrichment lineage. - `source_url` string, nullable — Original URL before S3 mirroring (for URL-based ingestion). - `object_key_source` string, nullable — S3 key source identifier. - `detected_mime_type` string, nullable — MIME type detected during canonicalization. - `history` object[], nullable — Processing steps history with timestamps and operations. - `taxonomy_lineage` object[], nullable — Taxonomy enrichment entries applied to this document. - `last_health_check` object, nullable — Last health check result (for batch processing). - `source_blobs` object[], nullable — Blobs that constituted the original source object. - `document_blobs` object[], nullable — Blobs generated during document processing (thumbnails, etc.). - `source_details` object[], nullable — Enrichment tracking and source detail entries. - `modality` string, nullable — Content modality (text, image, video, audio, etc.). - `metadata` object, nullable — System metadata including ingestion_status, feature_extractor_config_hash, and other processing-related information. - `mime_type` string, nullable — MIME type of the source content. - `size_bytes` integer, nullable — Size of the source content in bytes. - `content_hash` string, nullable — SHA256 hash of the source content for deduplication. - `_acl` InternalACLModel — Access control list for document-level security (row-level security). Controls which end-user principals can read/write a document. Used with user-scoped API keys (keys with principal_id set). Org-scoped keys bypass ACL entirely. - `owner` string, nullable — Principal ID of the document owner (the creator). - `read` string[], nullable — List of principal IDs that can read this document. - `write` string[], nullable — List of principal IDs that can write/update this document. - `public` boolean, nullable — If true, any user-scoped key can read this document. - `count` integer, required — Number of documents in this group. - `unknown_collection_ids` string[], 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. - `pagination` PaginationResponse, required — PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true - `total` integer, nullable - `page` integer, nullable - `page_size` integer, nullable - `total_pages` integer, nullable - `next_page` string, nullable - `previous_page` string, nullable - `next_cursor` string, nullable - `warnings` string[], 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_documents` integer, nullable — Total number of documents matching the query (across all pages). Alias for stats.total_documents — included at the top level for convenience. - `stats` DocumentListStats — Aggregate statistics for a list of documents. - `total_documents` integer, nullable — True total number of documents matching the collection/filter — populated only when `include_total=true` is requested (a COUNT query that adds ~50-200ms). `null` when not requested. This is NOT the page size; use `len(results)` for the number returned on this page. - `avg_blobs_per_document` number — Average number of source blobs per document - `total_groups` integer, nullable — Total number of groups when group_by is used. None for non-grouped results. - `avg_documents_per_group` number, nullable — Average number of documents per group when group_by is used. None for non-grouped results. - `group_by_field` string, 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. ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error --- [API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)