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

# Triggers

> Schedule clustering, taxonomy enrichment, and batch reruns on cron or intervals

Triggers run platform actions automatically — re-cluster a collection nightly, re-enrich documents as new data lands, or rerun a batch on a schedule. Instead of calling an endpoint by hand, you define *what* to run and *when*, and Mixpeek executes it.

## Anatomy of a trigger

Every trigger combines an **action** (what to run) with a **schedule** (when to run it):

```bash theme={null}
curl -sS -X POST "$MP_API_URL/v1/triggers" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "cluster",
    "action_config": { "cluster_id": "clust_abc123" },
    "trigger_type": "cron",
    "schedule_config": { "cron_expression": "0 2 * * *", "timezone": "UTC" },
    "description": "Daily clustering at 2am"
  }'
```

| Field | Description |
| - | - |
| `action_type` | What to run: `cluster`, `taxonomy_enrichment`, `batch_rerun`, `collection_trigger`, `retriever_execution`, `alert_evaluation`. |
| `action_config` | Action-specific config (e.g. `{ "cluster_id": "..." }`). |
| `trigger_type` | When to run: `cron`, `interval`, `conditional`. (`event` is accepted by the schema but currently rejected at create; see below.) |
| `schedule_config` | Schedule-specific config (cron expression, interval seconds, etc.). |
| `description` | Human-readable label. |
| `status` | `active` (default) or `paused`. |

## Schedule types

> [tab] Cron
>
> Run on a cron expression in a given timezone — best for fixed times ("every night at 2am").
>
> ```json theme={null}
> {
>   "trigger_type": "cron",
>   "schedule_config": { "cron_expression": "0 2 * * *", "timezone": "UTC" }
> }
> ```
>
> The expression is standard 5-field cron (`minute hour day-of-month month day-of-week`).

> [tab] Interval
>
> Run every N seconds — best for "keep it fresh" loops. Set `start_immediately` to run once on creation.
>
> ```json theme={null}
> {
>   "trigger_type": "interval",
>   "schedule_config": { "interval_seconds": 3600, "start_immediately": false }
> }
> ```

> [tab] Conditional
>
> Run when a condition is met (e.g. data drift or volume past a threshold). Provide the condition details in `schedule_config`. Use cron or interval for time-based schedules.
>
> Event-based triggers (fire in response to new documents or a completed batch, rather than a schedule) are not available yet: `trigger_type: "event"` is rejected at creation. Poll for the condition you need in the meantime, or use a short interval.

## Actions

### Cluster

Re-run a clustering definition on a schedule so groupings stay current as data grows.

```bash theme={null}
curl -sS -X POST "$MP_API_URL/v1/triggers" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "cluster",
    "action_config": {
      "cluster_id": "clust_abc123",
      "filters": { "status": "active" },
      "output_collection_ids": ["col_daily_clusters"]
    },
    "trigger_type": "cron",
    "schedule_config": { "cron_expression": "0 2 * * *", "timezone": "UTC" },
    "description": "Daily clustering of active items"
  }'
```

### Taxonomy enrichment

Re-classify a collection against a taxonomy. Use `incremental: true` to enrich only new documents — far cheaper than re-running the whole collection.

```bash theme={null}
curl -sS -X POST "$MP_API_URL/v1/triggers" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "taxonomy_enrichment",
    "action_config": {
      "collection_id": "col_inventory",
      "taxonomy_id": "tax_products",
      "incremental": true
    },
    "trigger_type": "interval",
    "schedule_config": { "interval_seconds": 3600 },
    "description": "Hourly incremental enrichment (only new docs)"
  }'
```

Enrich into a separate target collection on a nightly cron:

```bash theme={null}
curl -sS -X POST "$MP_API_URL/v1/triggers" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "taxonomy_enrichment",
    "action_config": {
      "collection_id": "col_inventory",
      "taxonomy_id": "tax_products",
      "target_collection_id": "col_enriched",
      "incremental": true,
      "batch_size": 500,
      "parallelism": 8
    },
    "trigger_type": "cron",
    "schedule_config": { "cron_expression": "0 3 * * *", "timezone": "UTC" },
    "description": "Nightly incremental enrichment to target collection"
  }'
```

> [!TIP]
>
> `incremental: true` only processes documents added since the last run, so it won't re-pay extraction/enrichment cost on documents already processed. Prefer it for recurring enrichment.

### Batch rerun & collection trigger

`batch_rerun` re-runs processing for a collection's documents; `collection_trigger` fires a collection's configured processing. Both take a `collection_id` in `action_config`.

### Alert evaluation

`alert_evaluation` evaluates one retriever alert on the trigger's cron or interval schedule. It takes an `alert_id` in `action_config`. While the trigger is active, the periodic alert evaluation skips that alert in this namespace, so it runs on this schedule only. See [Triggers vs Alerts](https://docs.mixpeek.com/docs/operations/triggers-vs-alerts.md).

## Manage triggers

| Operation | Endpoint |
| - | - |
| List | `POST /v1/triggers/list` |
| Get | `GET /v1/triggers/{trigger_id}` |
| Update | `PATCH /v1/triggers/{trigger_id}` |
| Run now | `POST /v1/triggers/{trigger_id}/execute` |
| Pause / resume | `POST /v1/triggers/{trigger_id}/pause` · `POST .../resume` |
| Run history | `GET /v1/triggers/{trigger_id}/history` |
| Delete | `DELETE /v1/triggers/{trigger_id}` |

Run a trigger on demand (outside its schedule) to test it:

```bash theme={null}
curl -sS -X POST "$MP_API_URL/v1/triggers/{trigger_id}/execute" \
  -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $MP_NAMESPACE"
```

Check recent runs and their outcomes:

```bash theme={null}
curl -sS "$MP_API_URL/v1/triggers/{trigger_id}/history" \
  -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $MP_NAMESPACE"
```

## Related

* [Clusters](https://docs.mixpeek.com/docs/enrichment/clusters.md) — define the clustering a `cluster` trigger reruns
* [Taxonomies](https://docs.mixpeek.com/docs/enrichment/taxonomies.md) — define the taxonomy a `taxonomy_enrichment` trigger applies
* [Alerts](https://docs.mixpeek.com/docs/enrichment/alerts.md) — get notified when content matches a condition
* [Storage syncs](https://docs.mixpeek.com/docs/tutorials/ingest-video-from-s3.md) — continuously ingest new files from object storage


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.