Skip to main content
POST
/
v1
/
clusters
/
triggers
Create Cluster Trigger
curl --request POST \
  --url https://api.mixpeek.com/v1/clusters/triggers \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '
{
  "trigger_type": "cron",
  "schedule_config": {},
  "cluster_id": "cluster_abc123",
  "execution_config": {
    "collection_ids": [
      "<string>"
    ],
    "config": {}
  },
  "description": "Daily clustering at 2am UTC",
  "status": "active"
}
'
{
  "namespace_id": "<string>",
  "internal_id": "<string>",
  "execution_config": {
    "collection_ids": [
      "<string>"
    ],
    "config": {}
  },
  "trigger_type": "cron",
  "schedule_config": {},
  "trigger_id": "<string>",
  "cluster_id": "<string>",
  "status": "active",
  "last_triggered_at": "2023-11-07T05:31:56Z",
  "last_execution_job_id": "<string>",
  "next_scheduled_at": "2023-11-07T05:31:56Z",
  "execution_count": 0,
  "consecutive_failures": 0,
  "last_execution_status": "<string>",
  "last_execution_error": "<string>",
  "event_counter": 0,
  "last_cooldown_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "description": "<string>"
}

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

​
X-Namespace
string
required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Body

application/json

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"
    }
​
trigger_type
enum<string>
required

REQUIRED. Type of trigger to create. Determines which schedule_config fields are required. Options: 'cron', 'interval', 'event', 'conditional'.

Available options:
cron,
interval,
event,
conditional
​
schedule_config
Schedule Config · object
required

REQUIRED. Type-specific schedule configuration. Contents depend on trigger_type. See trigger type examples above for required fields.

​
cluster_id
string | null

OPTIONAL. Reference to existing cluster definition. If provided, execution_config is inherited from the cluster. Either cluster_id OR execution_config must be provided.

Example:

"cluster_abc123"

​
execution_config
TriggerExecutionConfig · object

OPTIONAL. Clustering configuration for this trigger. Specifies collections and algorithm to use when trigger fires. Required if cluster_id is not provided.

​
description
string | null

OPTIONAL. Human-readable description of what this trigger does. Helpful for identifying triggers in dashboards.

Example:

"Daily clustering at 2am UTC"

​
status
enum<string>
default:active

OPTIONAL. Initial status of trigger. Defaults to 'active' (enabled). Can be set to 'paused' to create disabled trigger.

Available options:
active,
paused,
disabled,
failed

Response

Successful Response

Model for cluster trigger.

​
namespace_id
string
required

Namespace ID

​
internal_id
string
required

Organization internal ID

​
execution_config
TriggerExecutionConfig · object
required

Configuration for cluster execution

​
trigger_type
enum<string>
required

Type of trigger

Available options:
cron,
interval,
event,
conditional
​
schedule_config
Schedule Config · object
required

Type-specific schedule configuration

​
trigger_id
string

Unique trigger ID

​
cluster_id
string | null

Optional link to cluster definition

​
status
enum<string>
default:active

Current status

Available options:
active,
paused,
disabled,
failed
​
last_triggered_at
string<date-time> | null

Last time trigger fired

​
last_execution_job_id
string | null

Job ID of last execution

​
next_scheduled_at
string<date-time> | null

Next scheduled execution time

​
execution_count
integer
default:0

Total executions

​
consecutive_failures
integer
default:0

Consecutive execution failures

​
last_execution_status
string | null

Status of last execution

​
last_execution_error
string | null

Error from last execution

​
event_counter
integer
default:0

Current event count since last trigger

​
last_cooldown_at
string<date-time> | null

Last time cooldown was applied

​
created_at
string<date-time>

Creation timestamp

​
updated_at
string<date-time>

Last update timestamp

​
created_by
string | null

User who created trigger

​
description
string | null

Trigger description