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/
• task_id: Monitor via GET /tasks/

POST /v1/collections/{collection_identifier}/trigger

Trigger Collection Processing

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/collections/{collection_identifier}/trigger \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "include_buckets": [
    "<string>"
  ],
  "include_collections": [
    "<string>"
  ],
  "object_ids": [
    "<string>"
  ],
  "source_filters": {
    "AND": [
      {
        "field": "status",
        "operator": "eq",
        "value": "pending"
      }
    ]
  },
  "inputs": {
    "brand_id": "brand_42"
  },
  "reembed": {
    "dry_run": true,
    "outputs": [
      "transcription_embedding"
    ]
  }
}
'

202

{
  "task_id": "<string>",
  "collection_id": "<string>",
  "total_tiers": 123,
  "message": "<string>",
  "batch_id": "<string>",
  "source_bucket_ids": [
    "<string>"
  ],
  "source_collection_ids": [
    "<string>"
  ],
  "object_count": 123,
  "batch_ids": [
    "<string>"
  ],
  "task_ids": [
    "<string>"
  ],
  "batch_count": 123,
  "document_count": 123,
  "estimate": {
    "batch_id": "<string>",
    "collection_ids": [
      "<string>"
    ],
    "dedup_strategy": "skip",
    "object_count": 0,
    "already_extracted_count": 0,
    "estimated_credits": 0,
    "estimated_usd": 123,
    "estimated_repay_credits": 0,
    "features": [
      "<string>"
    ],
    "extractors": [
      "<string>"
    ],
    "content_summary": {},
    "documents_to_remove": 123,
    "warnings": [
      "<string>"
    ]
  }
}

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 or name of the collection to trigger

Body

application/json

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

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.

include_buckets · string[] | null

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 · string[] | null

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 · string[] | null

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 · LogicalOperator · object | null

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.

Show child attributes

Example:

{
  "AND": [
    {
      "field": "status",
      "operator": "eq",
      "value": "pending"
    }
  ]
}

dedup_strategy · enum<string> | null

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.

Available options: skip, replace, force

inputs · Inputs · object | null

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.

Example:

{ "brand_id": "brand_42" }

reembed · StoredTextReembedRequest · object | null

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.

Show child attributes

Example:

{
  "dry_run": true,
  "outputs": ["transcription_embedding"]
}

Response

202

application/json

Successful Response

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.

task_id · string · required

Task ID for monitoring via GET /v1/tasks/{task_id}.

collection_id · string · required

ID of the collection being processed.

total_tiers · integer · required

Number of processing tiers in the DAG.

message · string · required

Human-readable status message.

batch_id · string | null

ID of the created batch for tracking progress. Null for a stored-text re-embed (reembed), which runs as a task, not a batch.

source_bucket_ids · string[] | null

Bucket IDs that objects were discovered from (bucket-sourced collections).

source_collection_ids · string[] | null

Collection IDs that documents were read from (collection-sourced collections).

object_count · integer | null

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 · string[] | null

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 · string[] | null

Task IDs for each created batch, aligned with batch_ids.

batch_count · integer | null

Number of batches created. Null for a single-batch trigger; set when the load was auto-chunked into multiple batches.

document_count · integer | null

Total number of documents to process (collection-sourced collections).

estimate · BatchCostEstimate · object | null

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.

Show child attributes