> ## 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. # Create Cluster Trigger > 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) ## OpenAPI ````yaml post /v1/clusters/triggers 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: [] paths: /v1/clusters/triggers: post: tags: - Cluster Triggers summary: Create Cluster Trigger description: |- 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) operationId: create_trigger_v1_clusters_triggers_post parameters: [] requestBody: required: true content: application/json: schema: $ref: >- #/components/schemas/shared__clusters__triggers__models__CreateTriggerRequest responses: '201': description: Successful Response content: application/json: schema: $ref: >- #/components/schemas/shared__clusters__triggers__models__TriggerModel '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: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: shared__clusters__triggers__models__CreateTriggerRequest: properties: cluster_id: anyOf: - type: string - type: 'null' title: Cluster Id description: >- OPTIONAL. Reference to existing cluster definition. If provided, execution_config is inherited from the cluster. Either cluster_id OR execution_config must be provided. examples: - cluster_abc123 - null execution_config: anyOf: - $ref: '#/components/schemas/TriggerExecutionConfig' - type: 'null' description: >- OPTIONAL. Clustering configuration for this trigger. Specifies collections and algorithm to use when trigger fires. Required if cluster_id is not provided. trigger_type: $ref: '#/components/schemas/shared__clusters__triggers__models__TriggerType' description: >- REQUIRED. Type of trigger to create. Determines which schedule_config fields are required. Options: 'cron', 'interval', 'event', 'conditional'. schedule_config: additionalProperties: true type: object title: Schedule Config description: >- REQUIRED. Type-specific schedule configuration. Contents depend on trigger_type. See trigger type examples above for required fields. description: anyOf: - type: string - type: 'null' title: Description description: >- OPTIONAL. Human-readable description of what this trigger does. Helpful for identifying triggers in dashboards. examples: - Daily clustering at 2am UTC - Re-cluster after 100 documents - Maintain fresh clusters hourly status: $ref: >- #/components/schemas/shared__clusters__triggers__models__TriggerStatus description: >- OPTIONAL. Initial status of trigger. Defaults to 'active' (enabled). Can be set to 'paused' to create disabled trigger. default: active type: object required: - trigger_type - schedule_config title: CreateTriggerRequest description: >- 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" } examples: - description: Daily clustering at 2am UTC execution_config: collection_ids: - col_abc123 config: algorithm: kmeans min_cluster_size: 2 n_clusters: 5 schedule_config: cron_expression: 0 2 * * * timezone: UTC trigger_type: cron - description: Cluster every 6 hours execution_config: collection_ids: - col_products config: algorithm: hdbscan min_cluster_size: 10 min_samples: 5 schedule_config: interval_seconds: 21600 start_immediately: false trigger_type: interval - description: Cluster after 100 new documents execution_config: collection_ids: - col_abc123 config: algorithm: kmeans n_clusters: 3 schedule_config: collection_id: col_abc123 cooldown_seconds: 300 event_threshold: 100 event_type: documents_added trigger_type: event - description: Re-cluster when drift > 30% execution_config: collection_ids: - col_abc123 config: algorithm: hdbscan min_cluster_size: 5 schedule_config: check_interval_seconds: 3600 condition_type: drift metric: cosine_drift threshold: 0.3 trigger_type: conditional - cluster_id: cluster_xyz789 description: Hourly clustering using cluster_xyz789 schedule_config: interval_seconds: 3600 start_immediately: true trigger_type: interval shared__clusters__triggers__models__TriggerModel: properties: trigger_id: type: string title: Trigger Id description: Unique trigger ID cluster_id: anyOf: - type: string - type: 'null' title: Cluster Id description: Optional link to cluster definition namespace_id: type: string title: Namespace Id description: Namespace ID internal_id: type: string title: Internal Id description: Organization internal ID execution_config: $ref: '#/components/schemas/TriggerExecutionConfig' description: Configuration for cluster execution trigger_type: $ref: '#/components/schemas/shared__clusters__triggers__models__TriggerType' description: Type of trigger schedule_config: additionalProperties: true type: object title: Schedule Config description: Type-specific schedule configuration status: $ref: >- #/components/schemas/shared__clusters__triggers__models__TriggerStatus description: Current status default: active last_triggered_at: anyOf: - type: string format: date-time - type: 'null' title: Last Triggered At description: Last time trigger fired last_execution_job_id: anyOf: - type: string - type: 'null' title: Last Execution Job Id description: Job ID of last execution next_scheduled_at: anyOf: - type: string format: date-time - type: 'null' title: Next Scheduled At description: Next scheduled execution time execution_count: type: integer title: Execution Count description: Total executions default: 0 consecutive_failures: type: integer title: Consecutive Failures description: Consecutive execution failures default: 0 last_execution_status: anyOf: - type: string - type: 'null' title: Last Execution Status description: Status of last execution last_execution_error: anyOf: - type: string - type: 'null' title: Last Execution Error description: Error from last execution event_counter: type: integer title: Event Counter description: Current event count since last trigger default: 0 last_cooldown_at: anyOf: - type: string format: date-time - type: 'null' title: Last Cooldown At description: Last time cooldown was applied created_at: type: string format: date-time title: Created At description: Creation timestamp updated_at: type: string format: date-time title: Updated At description: Last update timestamp created_by: anyOf: - type: string - type: 'null' title: Created By description: User who created trigger description: anyOf: - type: string - type: 'null' title: Description description: Trigger description type: object required: - namespace_id - internal_id - execution_config - trigger_type - schedule_config title: TriggerModel description: Model for cluster trigger. 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 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TriggerExecutionConfig: properties: collection_ids: items: type: string type: array minItems: 1 title: Collection Ids description: >- 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. examples: - - col_abc123 - - col_products - col_inventory config: additionalProperties: true type: object title: Config description: >- 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'. examples: - algorithm: kmeans min_cluster_size: 2 n_clusters: 5 - algorithm: hdbscan min_cluster_size: 10 type: object required: - collection_ids - config title: TriggerExecutionConfig description: >- 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 } } shared__clusters__triggers__models__TriggerType: type: string enum: - cron - interval - event - conditional title: TriggerType description: >- 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) shared__clusters__triggers__models__TriggerStatus: type: string enum: - active - paused - disabled - failed title: TriggerStatus description: Status of a cluster trigger. 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. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ````