> ## 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, intervals, or events

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`. |
| `action_config`   | Action-specific config (e.g. `{ "cluster_id": "..." }`).                            |
| `trigger_type`    | When to run: `cron`, `interval`, `event`, `conditional`.                            |
| `schedule_config` | Schedule-specific config (cron expression, interval seconds, etc.).                 |
| `description`     | Human-readable label.                                                               |
| `status`          | `active` (default) or `paused`.                                                     |

## Schedule types

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="Event / Conditional">
    `event` triggers fire in response to platform events (e.g. new documents in a collection); `conditional` triggers fire when a condition is met. Provide the event/condition details in `schedule_config`. Use cron or interval for time-based schedules.
  </Tab>
</Tabs>

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

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

## 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](/enrichment/clusters) — define the clustering a `cluster` trigger reruns
* [Taxonomies](/enrichment/taxonomies) — define the taxonomy a `taxonomy_enrichment` trigger applies
* [Alerts](/enrichment/alerts) — get notified when content matches a condition
* [Storage syncs](/tutorials/ingest-video-from-s3) — continuously ingest new files from object storage