---
title: "Batch get documents by IDs"
method: POST
path: "/v1/documents/batch-get"
tags: ["Documents"]
---

# Batch get documents by IDs

`POST /v1/documents/batch-get`

Batch retrieve multiple documents by their IDs.

Returns documents and a list of IDs that were not found.
Maximum 1000 document IDs per request.

## Request body

- BatchGetDocumentsRequest — Batch retrieve documents by their IDs.
  - `document_ids` string[], required — List of document IDs to retrieve.
  - `return_presigned_urls` boolean — Generate presigned download URLs for document blobs.

## Response `200`

Successful Response

- BatchGetDocumentsResponse — Response for batch document retrieval.
  - `documents` DocumentResponse[] — Retrieved documents.
    - `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.
  - `not_found` string[] — Document IDs that were not found.

## 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/23e05292e326/schema)