> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Trigger Collection Processing > Process data through a collection - works for both bucket-sourced and collection-sourced collections. **For bucket-sourced collections:** Creates a batch and answers with its id and a task id, then reads the source bucket(s), splits a load over 1,000 objects into several batches, and submits them. Use `include_buckets` to limit which source buckets to process from. If the buckets hold no matching objects, or a submission is refused, the batch and the task read FAILED with the reason. The task lists every batch as `additional_data.trigger.batch_ids` once they are submitted. **For collection-sourced collections:** Processes existing documents from upstream collection(s). Use `include_collections` to limit which source collections to process from. **Filtering:** - `source_filters`: Field-level filters using LogicalOperator format - Example: `{"AND": [{"field": "status", "operator": "eq", "value": "pending"}]}` - For specific objects: `{"AND": [{"field": "object_id", "operator": "in", "value": ["obj_1", "obj_2"]}]}` **Returns:** - batch_id: Track progress via GET /batches/{batch_id} - task_id: Monitor via GET /tasks/{task_id} ## OpenAPI ````yaml post /v1/collections/{collection_identifier}/trigger openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: - BearerAuth: [] paths: /v1/collections/{collection_identifier}/trigger: post: tags: - Collections summary: Trigger Collection Processing description: >- Process data through a collection - works for both bucket-sourced and collection-sourced collections. **For bucket-sourced collections:** Creates a batch and answers with its id and a task id, then reads the source bucket(s), splits a load over 1,000 objects into several batches, and submits them. Use `include_buckets` to limit which source buckets to process from. If the buckets hold no matching objects, or a submission is refused, the batch and the task read FAILED with the reason. The task lists every batch as `additional_data.trigger.batch_ids` once they are submitted. **For collection-sourced collections:** Processes existing documents from upstream collection(s). Use `include_collections` to limit which source collections to process from. **Filtering:** - `source_filters`: Field-level filters using LogicalOperator format - Example: `{"AND": [{"field": "status", "operator": "eq", "value": "pending"}]}` - For specific objects: `{"AND": [{"field": "object_id", "operator": "in", "value": ["obj_1", "obj_2"]}]}` **Returns:** - batch_id: Track progress via GET /batches/{batch_id} - task_id: Monitor via GET /tasks/{task_id} operationId: trigger_collection_v1_collections__collection_identifier__trigger_post parameters: - name: collection_identifier in: path required: true schema: type: string description: The ID or name of the collection to trigger title: Collection Identifier description: The ID or name of the collection to trigger requestBody: content: application/json: schema: $ref: '#/components/schemas/TriggerCollectionRequest' description: >- Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02). x-unknown-keys: until: '2026-11-02' then: 422 extra_forbidden responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TriggerCollectionResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] NamespaceHeader: [] components: schemas: TriggerCollectionRequest: properties: include_buckets: anyOf: - items: type: string type: array - type: 'null' title: Include Buckets description: >- Limit processing to objects from these specific buckets (IDs or names). Only applies to bucket-sourced collections. If not provided, all configured source buckets are used. include_collections: anyOf: - items: type: string type: array - type: 'null' title: Include Collections description: >- Limit processing to documents from these specific collections (IDs or names). Only applies to collection-sourced collections. If not provided, all configured source collections are used. object_ids: anyOf: - items: type: string type: array - type: 'null' title: Object Ids description: >- Limit processing to these specific object IDs. Only applies to bucket-sourced collections. This is a convenience shorthand — equivalent to using source_filters with {"AND": [{"field": "object_id", "operator": "in", "value": [...]}]}. source_filters: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - type: 'null' description: >- Field-level filters for objects (bucket-sourced) or documents (collection-sourced). Uses LogicalOperator format (AND/OR/NOT). Use this to filter by metadata fields, status, or any other object/document properties. examples: - AND: - field: status operator: eq value: pending - AND: - field: object_id operator: in value: - obj_1 - obj_2 dedup_strategy: anyOf: - $ref: '#/components/schemas/DedupStrategy' - type: 'null' description: >- How to handle sources already processed in prior batches. `skip` (default): skip sources already materialized in this collection. `replace`: delete existing documents for the re-processed sources and re-materialize them — this also clears the processed-objects resume ledger, so use it to recover a collection stuck with ledger entries but 0 materialized documents (the orphan/divergence state). `force`: process regardless, allowing duplicates. inputs: anyOf: - additionalProperties: true type: object - type: 'null' title: Inputs description: >- Values for the retriever transform's INPUT fields, for a collection built by a retriever transform from source collections. The build runs the transform's retriever with these inputs, so one view definition can build per scope: trigger it once per brand, team or tenant with that scope's values, and combine source_filters to read only that scope's source documents. Checked against the transform retriever's input_schema like an execute request: a missing required field is a 422, an unknown key a 400, and a field left out takes its schema default. Refused for a collection with no retriever transform, and together with dedup_strategy 'replace', which could delete rows another scope's build wrote from the same sources. A transform's own templates can write an input into each output row, and a composite unique_id_field keeps one row per scope and source. A build adds and updates rows and deletes none: when a source document leaves a scope, its row for that scope stays until you delete it with DELETE /v1/collections/{collection_id}/documents/batch. A build that starts without inputs (an ingest into a source collection, an alert, a backfill or a refresh) fails its job when the retriever requires an input. examples: - brand_id: brand_42 reembed: anyOf: - $ref: '#/components/schemas/StoredTextReembedRequest' - type: 'null' description: >- Re-embed stored document text instead of reprocessing sources. When set, no batch is created: the collection's existing documents are read, the selected embedding outputs are recomputed from the text each document already stores, and the vectors are written back onto the same documents. Progress is reported on the returned task. Source selection fields (include_buckets, include_collections, object_ids, source_filters, dedup_strategy) cannot be combined with it. examples: - dry_run: true outputs: - transcription_embedding - document_ids: - doc_1 - doc_2 outputs: - transcription_embedding type: object title: TriggerCollectionRequest description: >- Request to trigger (re)processing through a collection. **For bucket-sourced collections (tier 0):** Discovers objects from source bucket(s) and creates a batch for processing. Use `include_buckets` to limit which source buckets to process from. **For collection-sourced collections (tier N):** Processes existing documents from upstream collection(s). Use `include_collections` to limit which source collections to process from. Use `source_filters` for field-level filtering on objects or documents. **Document Overwrite Behavior:** - If source bucket has `unique_key` configured: Documents are UPSERTED (overwrites existing) - If source bucket has NO `unique_key`: New documents are CREATED (may cause duplicates) To enable idempotent re-processing, configure `unique_key` on the source bucket. TriggerCollectionResponse: properties: batch_id: anyOf: - type: string - type: 'null' title: Batch Id description: >- ID of the created batch for tracking progress. Null for a stored-text re-embed (`reembed`), which runs as a task, not a batch. task_id: type: string title: Task Id description: Task ID for monitoring via GET /v1/tasks/{task_id}. collection_id: type: string title: Collection Id description: ID of the collection being processed. source_bucket_ids: anyOf: - items: type: string type: array - type: 'null' title: Source Bucket Ids description: >- Bucket IDs that objects were discovered from (bucket-sourced collections). source_collection_ids: anyOf: - items: type: string type: array - type: 'null' title: Source Collection Ids description: >- Collection IDs that documents were read from (collection-sourced collections). object_count: anyOf: - type: integer - type: 'null' title: Object Count description: >- Number of objects in the trigger (bucket-sourced collections). Null when the trigger answered before reading the bucket; the count is then on the task, as `additional_data.trigger.object_count`. batch_ids: anyOf: - items: type: string type: array - type: 'null' title: Batch Ids description: >- All batch IDs created for this trigger. Present when a large load was auto-chunked into multiple right-sized batches; `batch_id` is the first of these. Null (absent) for a single-batch trigger, and when the trigger answered before reading the bucket: the task then lists them as `additional_data.trigger.batch_ids`. task_ids: anyOf: - items: type: string type: array - type: 'null' title: Task Ids description: Task IDs for each created batch, aligned with `batch_ids`. batch_count: anyOf: - type: integer - type: 'null' title: Batch Count description: >- Number of batches created. Null for a single-batch trigger; set when the load was auto-chunked into multiple batches. document_count: anyOf: - type: integer - type: 'null' title: Document Count description: >- Total number of documents to process (collection-sourced collections). total_tiers: type: integer title: Total Tiers description: Number of processing tiers in the DAG. message: type: string title: Message description: Human-readable status message. estimate: anyOf: - $ref: '#/components/schemas/BatchCostEstimate' - type: 'null' description: >- OPTIONAL. What this trigger was estimated to cost when it was submitted: the same calculation submit bills by, read from each batch before it ran, summed over the batches when the load was split. Absent for a collection-sourced trigger, when the estimate could not be computed in time, and when the trigger answered before reading the bucket: each batch's task then carries it as `additional_data.estimate`. type: object required: - task_id - collection_id - total_tiers - message title: TriggerCollectionResponse description: >- Response after triggering collection processing. Use `batch_id` or `task_id` to monitor progress via GET /v1/batches/{batch_id} or GET /v1/tasks/{task_id}. A bucket-sourced trigger answers before it has read the bucket: the batch starts in DRAFT with no objects, and the task reads FAILED with the reason if the bucket has no matching objects or the submission is refused. ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false LogicalOperator-Input: properties: AND: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: And description: Logical AND operation - all conditions must be true example: - field: name operator: eq value: John - field: age operator: gte value: 30 OR: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: Or description: Logical OR operation - at least one condition must be true example: - field: status operator: eq value: active - field: role operator: eq value: admin NOT: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: Not description: Logical NOT operation - all conditions must be false example: - field: department operator: eq value: HR - field: location operator: eq value: remote case_sensitive: anyOf: - type: boolean - type: 'null' title: Case Sensitive description: Whether to perform case-sensitive matching default: false example: true additionalProperties: true type: object title: LogicalOperator description: >- 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"}). DedupStrategy: type: string enum: - skip - replace - force title: DedupStrategy description: |- Controls how duplicate objects are handled during batch processing. Dedup is scoped to (bucket_id, collection_id): an object is considered a duplicate if the target collection already has documents produced from the same source object in any prior batch. StoredTextReembedRequest: properties: outputs: items: type: string const: transcription_embedding type: array title: Outputs description: >- The embedding outputs to recompute from stored text. `transcription_embedding` re-embeds each document's stored `transcription` into the multimodal_extractor v2 transcription index (requires a multimodal_extractor v2 collection with run_transcription_embedding enabled). Give `outputs` or `target_feature_uri`. target_feature_uri: anyOf: - type: string - type: 'null' title: Target Feature Uri description: >- Re-embed each document's stored text with another embedding model, named by its feature URI: the collection's own URI with the new model's name as the output, for example `mixpeek://text_extractor@v1/all_minilm_l6_v2_v1` on a text_extractor v1 collection. The vectors are written under the new model's own index beside the existing ones, so searches keep answering from the current URI while this runs. When it completes the collection lists the new URI in `vector_indexes`, and setting `index_map` makes it answer searches. Give `outputs` or `target_feature_uri`. examples: - mixpeek://text_extractor@v1/all_minilm_l6_v2_v1 document_ids: anyOf: - items: type: string type: array maxItems: 10000 minItems: 1 - type: 'null' title: Document Ids description: >- Limit the re-embed to these document ids. When omitted, every document in the collection is considered. only_missing: type: boolean title: Only Missing description: >- Re-embed only documents that have text but no vector in the target index. Documents whose vector cannot be confirmed present are re-embedded, which is safe because the same text always produces the same vector. Set false to re-embed every document with text. default: true dry_run: type: boolean title: Dry Run description: >- Count what would be re-embedded without writing anything. The counts are recorded on the task (GET /v1/tasks/{task_id}). default: false type: object title: StoredTextReembedRequest description: >- Re-embed stored document text into an existing vector index. Recomputes one text embedding output from the text the collection already stored on each document, and writes the vector back onto the same document. Nothing else runs: no media download, no transcription, no other embeddings. Document ids, payload fields and every other vector are left as they are. BatchCostEstimate: properties: batch_id: type: string title: Batch Id collection_ids: items: type: string type: array title: Collection Ids dedup_strategy: type: string title: Dedup Strategy description: skip | replace | force — controls re-extraction default: skip object_count: type: integer title: Object Count description: Objects this batch will process default: 0 already_extracted_count: type: integer title: Already Extracted Count description: >- Objects in this batch already extracted before (re-paid under force/replace) default: 0 estimated_credits: type: integer title: Estimated Credits description: Credits submitting this batch will consume (same calc as submit) default: 0 estimated_usd: anyOf: - type: number - type: 'null' title: Estimated Usd description: >- Dollar cost of this batch under live v2 pricing (file type × amount × search-by features). Credits are milli-dollars of this value. estimated_repay_credits: type: integer title: Estimated Repay Credits description: >- ~credits re-paying already-extracted objects (force/replace only; linear approx) default: 0 features: items: type: string type: array title: Features description: >- What this batch searches by (dimension 3 of pricing): feature keys billed per file type; custom plugins as 'custom:'. extractors: items: type: string type: array title: Extractors description: >- Internal implementation of `features` — prefer rendering `features`; extractor names are the deeper disclosure layer. content_summary: anyOf: - additionalProperties: true type: object - type: 'null' title: Content Summary description: >- Dimensions 1+2 of pricing: file types and how much of each (counts, video minutes, pages, tokens…) documents_to_remove: anyOf: - type: integer - type: 'null' title: Documents To Remove description: >- OPTIONAL. For dedup_strategy replace: the documents the batch's objects have now in its collections. A replace removes each of these that its re-run does not overwrite in place, after the new documents are written, so this is the most it removes. Absent for skip and force. warnings: items: type: string type: array title: Warnings type: object required: - batch_id title: BatchCostEstimate description: Dry-run estimate of what submitting a DRAFT batch will cost + re-pay. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. FilterCondition: properties: field: type: string title: Field description: Field name to filter on operator: $ref: '#/components/schemas/FilterOperator' description: Comparison operator default: eq value: anyOf: - $ref: '#/components/schemas/DynamicValue' - {} title: Value description: Value to compare against type: object required: - field - value title: FilterCondition description: |- Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against FilterOperator: description: >- Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem. enum: - eq - ne - gt - lt - gte - lte - in - nin - contains - starts_with - ends_with - regex - exists - is_null - text - phrase - words - geo_radius - geo_bounding_box - geo_polygon title: FilterOperator type: string DynamicValue: description: A value that should be dynamically resolved from the query request. properties: type: type: string const: dynamic title: Type default: dynamic field: type: string title: Field description: >- The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id' examples: - inputs.query_text - filters.AND[0].value required: - field title: DynamicValue type: object securitySchemes: BearerAuth: type: http scheme: bearer description: >- 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. NamespaceHeader: type: apiKey in: header name: X-Namespace description: >- 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`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.