---
title: "Create Cluster Trigger"
method: POST
path: "/v1/clusters/triggers"
tags: ["Cluster Triggers"]
---

# Create Cluster Trigger

`POST /v1/clusters/triggers`

Create a new trigger for automated cluster execution.

    Supports multiple trigger types:
    - **cron**: Execute at specific times using cron expressions
    - **interval**: Execute at fixed intervals
    - **event**: Execute when specific events occur (e.g., documents added)
    - **conditional**: Execute when conditions are met (e.g., drift threshold)

## Request body

- SharedClustersTriggersModelsCreateTriggerRequest — Request to create a new cluster trigger. Creates an automated trigger that executes clustering based on schedules, events, or conditions. Requirements: - trigger_type: REQUIRED - Determines which schedule_config fields are needed - schedule_config: REQUIRED - Configuration specific to trigger_type - execution_config OR cluster_id: REQUIRED - Either provide config directly or reference existing cluster Trigger Types and schedule_config: - **cron**: Requires {"cron_expression": str, "timezone": str} - **interval**: Requires {"interval_seconds": int, "start_immediately": bool} - **event**: Requires {"event_type": str, "event_threshold": int, "collection_id": str, "cooldown_seconds": int} - **conditional**: Requires {"condition_type": str, "threshold": float, "metric": str, "check_interval_seconds": int} Use Cases: - Scheduled maintenance: Use cron or interval triggers - Reactive clustering: Use event triggers to cluster when data changes - Intelligent clustering: Use conditional triggers based on metrics Examples: Cron trigger (daily at 2am UTC): { "trigger_type": "cron", "schedule_config": { "cron_expression": "0 2 * * *", "timezone": "UTC" }, "execution_config": { "collection_ids": ["col_abc123"], "config": { "algorithm": "kmeans", "n_clusters": 5 } }, "description": "Daily clustering at 2am" } Interval trigger (every 6 hours): { "trigger_type": "interval", "schedule_config": { "interval_seconds": 21600, "start_immediately": false }, "execution_config": { "collection_ids": ["col_products"], "config": { "algorithm": "hdbscan", "min_cluster_size": 10 } }, "description": "Cluster every 6 hours" } Event trigger (after 100 documents added): { "trigger_type": "event", "schedule_config": { "event_type": "documents_added", "event_threshold": 100, "collection_id": "col_abc123", "cooldown_seconds": 300 }, "execution_config": { "collection_ids": ["col_abc123"], "config": { "algorithm": "kmeans", "n_clusters": 3 } }, "description": "Cluster after 100 new documents" } Conditional trigger (when drift exceeds 30%): { "trigger_type": "conditional", "schedule_config": { "condition_type": "drift", "threshold": 0.3, "metric": "cosine_drift", "check_interval_seconds": 3600 }, "execution_config": { "collection_ids": ["col_abc123"], "config": { "algorithm": "hdbscan", "min_cluster_size": 5 } }, "description": "Re-cluster when drift > 30%" } Using existing cluster definition: { "trigger_type": "interval", "schedule_config": { "interval_seconds": 3600, "start_immediately": true }, "cluster_id": "cluster_xyz789", "description": "Hourly clustering using cluster_xyz789" }
  - `cluster_id` string, nullable — OPTIONAL. Reference to existing cluster definition. If provided, execution_config is inherited from the cluster. Either cluster_id OR execution_config must be provided.
  - `execution_config` TriggerExecutionConfig — Configuration for cluster execution when trigger fires. Defines what clustering algorithm and parameters to use when the trigger executes. Examples: K-means clustering on 3 collections: { "collection_ids": ["col_abc123", "col_def456", "col_ghi789"], "config": { "algorithm": "kmeans", "n_clusters": 5, "min_cluster_size": 2 } } HDBSCAN clustering on single collection: { "collection_ids": ["col_products"], "config": { "algorithm": "hdbscan", "min_cluster_size": 10, "min_samples": 5 } }
    - `collection_ids` string[], required — REQUIRED. List of collection IDs to cluster when trigger fires. Must contain at least one collection ID. All collections will be clustered together using the specified algorithm.
    - `config` object, required — REQUIRED. Clustering algorithm configuration. Must include 'algorithm' field ('kmeans', 'hdbscan', 'hierarchical'). Additional fields depend on algorithm choice. K-means requires 'n_clusters'. HDBSCAN requires 'min_cluster_size'.
  - `trigger_type` 'cron' | 'interval' | 'event' | 'conditional', required — Type of trigger for automated cluster execution. Supported trigger types: - **cron**: Schedule-based execution using cron expressions (e.g., daily at 2am) - **interval**: Fixed-interval execution (e.g., every 6 hours) - **event**: Event-driven execution (e.g., after 100 documents added) - **conditional**: Condition-based execution (e.g., when drift exceeds threshold)
  - `schedule_config` object, required — REQUIRED. Type-specific schedule configuration. Contents depend on trigger_type. See trigger type examples above for required fields.
  - `description` string, nullable — OPTIONAL. Human-readable description of what this trigger does. Helpful for identifying triggers in dashboards.
  - `status` 'active' | 'paused' | 'disabled' | 'failed' — Status of a cluster trigger.

## Response `201`

Successful Response

- SharedClustersTriggersModelsTriggerModel — Model for cluster trigger.
  - `trigger_id` string — Unique trigger ID
  - `cluster_id` string, nullable — Optional link to cluster definition
  - `namespace_id` string, required — Namespace ID
  - `internal_id` string, required — Organization internal ID
  - `execution_config` TriggerExecutionConfig, required — Configuration for cluster execution when trigger fires. Defines what clustering algorithm and parameters to use when the trigger executes. Examples: K-means clustering on 3 collections: { "collection_ids": ["col_abc123", "col_def456", "col_ghi789"], "config": { "algorithm": "kmeans", "n_clusters": 5, "min_cluster_size": 2 } } HDBSCAN clustering on single collection: { "collection_ids": ["col_products"], "config": { "algorithm": "hdbscan", "min_cluster_size": 10, "min_samples": 5 } }
    - `collection_ids` string[], required — REQUIRED. List of collection IDs to cluster when trigger fires. Must contain at least one collection ID. All collections will be clustered together using the specified algorithm.
    - `config` object, required — REQUIRED. Clustering algorithm configuration. Must include 'algorithm' field ('kmeans', 'hdbscan', 'hierarchical'). Additional fields depend on algorithm choice. K-means requires 'n_clusters'. HDBSCAN requires 'min_cluster_size'.
  - `trigger_type` 'cron' | 'interval' | 'event' | 'conditional', required — Type of trigger for automated cluster execution. Supported trigger types: - **cron**: Schedule-based execution using cron expressions (e.g., daily at 2am) - **interval**: Fixed-interval execution (e.g., every 6 hours) - **event**: Event-driven execution (e.g., after 100 documents added) - **conditional**: Condition-based execution (e.g., when drift exceeds threshold)
  - `schedule_config` object, required — Type-specific schedule configuration
  - `status` 'active' | 'paused' | 'disabled' | 'failed' — Status of a cluster trigger.
  - `last_triggered_at` string, date-time, nullable — Last time trigger fired
  - `last_execution_job_id` string, nullable — Job ID of last execution
  - `next_scheduled_at` string, date-time, nullable — Next scheduled execution time
  - `execution_count` integer — Total executions
  - `consecutive_failures` integer — Consecutive execution failures
  - `last_execution_status` string, nullable — Status of last execution
  - `last_execution_error` string, nullable — Error from last execution
  - `event_counter` integer — Current event count since last trigger
  - `last_cooldown_at` string, date-time, nullable — Last time cooldown was applied
  - `created_at` string, date-time — Creation timestamp
  - `updated_at` string, date-time — Last update timestamp
  - `created_by` string, nullable — User who created trigger
  - `description` string, nullable — Trigger description

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