Partially Update Cluster
curl --request PATCH \
--url https://api.mixpeek.com/v1/clusters/{cluster_identifier} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"cluster_name": "<string>",
"description": "<string>",
"metadata": {},
"llm_labeling": {
"enabled": true,
"include_keywords": true,
"include_summary": true,
"labeling_inputs": {
"input_mappings": [
{
"input_key": "title",
"path": "title",
"source_type": "payload"
},
{
"input_key": "description",
"path": "description",
"source_type": "payload"
},
{
"input_key": "text",
"path": "text",
"source_type": "payload"
}
]
},
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
},
"filters": {},
"face_cluster_merge": {
"enabled": true,
"centroid_cosine_threshold": 0.55,
"bbox_iou_threshold": 0.4,
"scene_jaccard_threshold": 0.3,
"bbox_field": "bbox",
"frame_field": "frame_number",
"scene_field": "scene_id"
},
"sample_size": 123,
"algorithm_params": {}
}
'import requests
url = "https://api.mixpeek.com/v1/clusters/{cluster_identifier}"
payload = {
"cluster_name": "<string>",
"description": "<string>",
"metadata": {},
"llm_labeling": {
"enabled": True,
"include_keywords": True,
"include_summary": True,
"labeling_inputs": { "input_mappings": [
{
"input_key": "title",
"path": "title",
"source_type": "payload"
},
{
"input_key": "description",
"path": "description",
"source_type": "payload"
},
{
"input_key": "text",
"path": "text",
"source_type": "payload"
}
] },
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
},
"filters": {},
"face_cluster_merge": {
"enabled": True,
"centroid_cosine_threshold": 0.55,
"bbox_iou_threshold": 0.4,
"scene_jaccard_threshold": 0.3,
"bbox_field": "bbox",
"frame_field": "frame_number",
"scene_field": "scene_id"
},
"sample_size": 123,
"algorithm_params": {}
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
cluster_name: '<string>',
description: '<string>',
metadata: {},
llm_labeling: {
enabled: true,
include_keywords: true,
include_summary: true,
labeling_inputs: {
input_mappings: [
{input_key: 'title', path: 'title', source_type: 'payload'},
{input_key: 'description', path: 'description', source_type: 'payload'},
{input_key: 'text', path: 'text', source_type: 'payload'}
]
},
model_name: 'gpt-4o-mini-2024-07-18',
provider: 'openai'
},
filters: {},
face_cluster_merge: {
enabled: true,
centroid_cosine_threshold: 0.55,
bbox_iou_threshold: 0.4,
scene_jaccard_threshold: 0.3,
bbox_field: 'bbox',
frame_field: 'frame_number',
scene_field: 'scene_id'
},
sample_size: 123,
algorithm_params: {}
})
};
fetch('https://api.mixpeek.com/v1/clusters/{cluster_identifier}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/clusters/{cluster_identifier}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'cluster_name' => '<string>',
'description' => '<string>',
'metadata' => [
],
'llm_labeling' => [
'enabled' => true,
'include_keywords' => true,
'include_summary' => true,
'labeling_inputs' => [
'input_mappings' => [
[
'input_key' => 'title',
'path' => 'title',
'source_type' => 'payload'
],
[
'input_key' => 'description',
'path' => 'description',
'source_type' => 'payload'
],
[
'input_key' => 'text',
'path' => 'text',
'source_type' => 'payload'
]
]
],
'model_name' => 'gpt-4o-mini-2024-07-18',
'provider' => 'openai'
],
'filters' => [
],
'face_cluster_merge' => [
'enabled' => true,
'centroid_cosine_threshold' => 0.55,
'bbox_iou_threshold' => 0.4,
'scene_jaccard_threshold' => 0.3,
'bbox_field' => 'bbox',
'frame_field' => 'frame_number',
'scene_field' => 'scene_id'
],
'sample_size' => 123,
'algorithm_params' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/clusters/{cluster_identifier}"
payload := strings.NewReader("{\n \"cluster_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"llm_labeling\": {\n \"enabled\": true,\n \"include_keywords\": true,\n \"include_summary\": true,\n \"labeling_inputs\": {\n \"input_mappings\": [\n {\n \"input_key\": \"title\",\n \"path\": \"title\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"description\",\n \"path\": \"description\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"text\",\n \"path\": \"text\",\n \"source_type\": \"payload\"\n }\n ]\n },\n \"model_name\": \"gpt-4o-mini-2024-07-18\",\n \"provider\": \"openai\"\n },\n \"filters\": {},\n \"face_cluster_merge\": {\n \"enabled\": true,\n \"centroid_cosine_threshold\": 0.55,\n \"bbox_iou_threshold\": 0.4,\n \"scene_jaccard_threshold\": 0.3,\n \"bbox_field\": \"bbox\",\n \"frame_field\": \"frame_number\",\n \"scene_field\": \"scene_id\"\n },\n \"sample_size\": 123,\n \"algorithm_params\": {}\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.mixpeek.com/v1/clusters/{cluster_identifier}")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cluster_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"llm_labeling\": {\n \"enabled\": true,\n \"include_keywords\": true,\n \"include_summary\": true,\n \"labeling_inputs\": {\n \"input_mappings\": [\n {\n \"input_key\": \"title\",\n \"path\": \"title\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"description\",\n \"path\": \"description\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"text\",\n \"path\": \"text\",\n \"source_type\": \"payload\"\n }\n ]\n },\n \"model_name\": \"gpt-4o-mini-2024-07-18\",\n \"provider\": \"openai\"\n },\n \"filters\": {},\n \"face_cluster_merge\": {\n \"enabled\": true,\n \"centroid_cosine_threshold\": 0.55,\n \"bbox_iou_threshold\": 0.4,\n \"scene_jaccard_threshold\": 0.3,\n \"bbox_field\": \"bbox\",\n \"frame_field\": \"frame_number\",\n \"scene_field\": \"scene_id\"\n },\n \"sample_size\": 123,\n \"algorithm_params\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/clusters/{cluster_identifier}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cluster_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"llm_labeling\": {\n \"enabled\": true,\n \"include_keywords\": true,\n \"include_summary\": true,\n \"labeling_inputs\": {\n \"input_mappings\": [\n {\n \"input_key\": \"title\",\n \"path\": \"title\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"description\",\n \"path\": \"description\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"text\",\n \"path\": \"text\",\n \"source_type\": \"payload\"\n }\n ]\n },\n \"model_name\": \"gpt-4o-mini-2024-07-18\",\n \"provider\": \"openai\"\n },\n \"filters\": {},\n \"face_cluster_merge\": {\n \"enabled\": true,\n \"centroid_cosine_threshold\": 0.55,\n \"bbox_iou_threshold\": 0.4,\n \"scene_jaccard_threshold\": 0.3,\n \"bbox_field\": \"bbox\",\n \"frame_field\": \"frame_number\",\n \"scene_field\": \"scene_id\"\n },\n \"sample_size\": 123,\n \"algorithm_params\": {}\n}"
response = http.request(request)
puts response.read_body{
"cluster_name": "products_clip_hdbscan",
"cluster_type": "vector",
"collection_ids": [
"col_products_v1",
"col_products_v2"
],
"llm_labeling": {
"enabled": true,
"labeling_inputs": {
"input_mappings": [
{
"input_key": "text",
"path": "description",
"source_type": "payload"
}
]
},
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
},
"vector_config": {
"clustering_method": "hdbscan",
"feature_uri": "mixpeek://clip_vit_l_14@v1/embedding",
"hdbscan_parameters": {
"min_cluster_size": 10,
"min_samples": 5
},
"sample_size": 5000
}
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Clusters
Partially Update Cluster
This endpoint partially updates a cluster (PATCH operation). Only provided fields will be updated. At minimum, metadata can always be updated. Immutable fields like cluster_id, status, and computed fields cannot be modified.
PATCH
/
v1
/
clusters
/
{cluster_identifier}
Partially Update Cluster
curl --request PATCH \
--url https://api.mixpeek.com/v1/clusters/{cluster_identifier} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"cluster_name": "<string>",
"description": "<string>",
"metadata": {},
"llm_labeling": {
"enabled": true,
"include_keywords": true,
"include_summary": true,
"labeling_inputs": {
"input_mappings": [
{
"input_key": "title",
"path": "title",
"source_type": "payload"
},
{
"input_key": "description",
"path": "description",
"source_type": "payload"
},
{
"input_key": "text",
"path": "text",
"source_type": "payload"
}
]
},
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
},
"filters": {},
"face_cluster_merge": {
"enabled": true,
"centroid_cosine_threshold": 0.55,
"bbox_iou_threshold": 0.4,
"scene_jaccard_threshold": 0.3,
"bbox_field": "bbox",
"frame_field": "frame_number",
"scene_field": "scene_id"
},
"sample_size": 123,
"algorithm_params": {}
}
'import requests
url = "https://api.mixpeek.com/v1/clusters/{cluster_identifier}"
payload = {
"cluster_name": "<string>",
"description": "<string>",
"metadata": {},
"llm_labeling": {
"enabled": True,
"include_keywords": True,
"include_summary": True,
"labeling_inputs": { "input_mappings": [
{
"input_key": "title",
"path": "title",
"source_type": "payload"
},
{
"input_key": "description",
"path": "description",
"source_type": "payload"
},
{
"input_key": "text",
"path": "text",
"source_type": "payload"
}
] },
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
},
"filters": {},
"face_cluster_merge": {
"enabled": True,
"centroid_cosine_threshold": 0.55,
"bbox_iou_threshold": 0.4,
"scene_jaccard_threshold": 0.3,
"bbox_field": "bbox",
"frame_field": "frame_number",
"scene_field": "scene_id"
},
"sample_size": 123,
"algorithm_params": {}
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
cluster_name: '<string>',
description: '<string>',
metadata: {},
llm_labeling: {
enabled: true,
include_keywords: true,
include_summary: true,
labeling_inputs: {
input_mappings: [
{input_key: 'title', path: 'title', source_type: 'payload'},
{input_key: 'description', path: 'description', source_type: 'payload'},
{input_key: 'text', path: 'text', source_type: 'payload'}
]
},
model_name: 'gpt-4o-mini-2024-07-18',
provider: 'openai'
},
filters: {},
face_cluster_merge: {
enabled: true,
centroid_cosine_threshold: 0.55,
bbox_iou_threshold: 0.4,
scene_jaccard_threshold: 0.3,
bbox_field: 'bbox',
frame_field: 'frame_number',
scene_field: 'scene_id'
},
sample_size: 123,
algorithm_params: {}
})
};
fetch('https://api.mixpeek.com/v1/clusters/{cluster_identifier}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/clusters/{cluster_identifier}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'cluster_name' => '<string>',
'description' => '<string>',
'metadata' => [
],
'llm_labeling' => [
'enabled' => true,
'include_keywords' => true,
'include_summary' => true,
'labeling_inputs' => [
'input_mappings' => [
[
'input_key' => 'title',
'path' => 'title',
'source_type' => 'payload'
],
[
'input_key' => 'description',
'path' => 'description',
'source_type' => 'payload'
],
[
'input_key' => 'text',
'path' => 'text',
'source_type' => 'payload'
]
]
],
'model_name' => 'gpt-4o-mini-2024-07-18',
'provider' => 'openai'
],
'filters' => [
],
'face_cluster_merge' => [
'enabled' => true,
'centroid_cosine_threshold' => 0.55,
'bbox_iou_threshold' => 0.4,
'scene_jaccard_threshold' => 0.3,
'bbox_field' => 'bbox',
'frame_field' => 'frame_number',
'scene_field' => 'scene_id'
],
'sample_size' => 123,
'algorithm_params' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/clusters/{cluster_identifier}"
payload := strings.NewReader("{\n \"cluster_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"llm_labeling\": {\n \"enabled\": true,\n \"include_keywords\": true,\n \"include_summary\": true,\n \"labeling_inputs\": {\n \"input_mappings\": [\n {\n \"input_key\": \"title\",\n \"path\": \"title\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"description\",\n \"path\": \"description\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"text\",\n \"path\": \"text\",\n \"source_type\": \"payload\"\n }\n ]\n },\n \"model_name\": \"gpt-4o-mini-2024-07-18\",\n \"provider\": \"openai\"\n },\n \"filters\": {},\n \"face_cluster_merge\": {\n \"enabled\": true,\n \"centroid_cosine_threshold\": 0.55,\n \"bbox_iou_threshold\": 0.4,\n \"scene_jaccard_threshold\": 0.3,\n \"bbox_field\": \"bbox\",\n \"frame_field\": \"frame_number\",\n \"scene_field\": \"scene_id\"\n },\n \"sample_size\": 123,\n \"algorithm_params\": {}\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.mixpeek.com/v1/clusters/{cluster_identifier}")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cluster_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"llm_labeling\": {\n \"enabled\": true,\n \"include_keywords\": true,\n \"include_summary\": true,\n \"labeling_inputs\": {\n \"input_mappings\": [\n {\n \"input_key\": \"title\",\n \"path\": \"title\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"description\",\n \"path\": \"description\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"text\",\n \"path\": \"text\",\n \"source_type\": \"payload\"\n }\n ]\n },\n \"model_name\": \"gpt-4o-mini-2024-07-18\",\n \"provider\": \"openai\"\n },\n \"filters\": {},\n \"face_cluster_merge\": {\n \"enabled\": true,\n \"centroid_cosine_threshold\": 0.55,\n \"bbox_iou_threshold\": 0.4,\n \"scene_jaccard_threshold\": 0.3,\n \"bbox_field\": \"bbox\",\n \"frame_field\": \"frame_number\",\n \"scene_field\": \"scene_id\"\n },\n \"sample_size\": 123,\n \"algorithm_params\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/clusters/{cluster_identifier}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cluster_name\": \"<string>\",\n \"description\": \"<string>\",\n \"metadata\": {},\n \"llm_labeling\": {\n \"enabled\": true,\n \"include_keywords\": true,\n \"include_summary\": true,\n \"labeling_inputs\": {\n \"input_mappings\": [\n {\n \"input_key\": \"title\",\n \"path\": \"title\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"description\",\n \"path\": \"description\",\n \"source_type\": \"payload\"\n },\n {\n \"input_key\": \"text\",\n \"path\": \"text\",\n \"source_type\": \"payload\"\n }\n ]\n },\n \"model_name\": \"gpt-4o-mini-2024-07-18\",\n \"provider\": \"openai\"\n },\n \"filters\": {},\n \"face_cluster_merge\": {\n \"enabled\": true,\n \"centroid_cosine_threshold\": 0.55,\n \"bbox_iou_threshold\": 0.4,\n \"scene_jaccard_threshold\": 0.3,\n \"bbox_field\": \"bbox\",\n \"frame_field\": \"frame_number\",\n \"scene_field\": \"scene_id\"\n },\n \"sample_size\": 123,\n \"algorithm_params\": {}\n}"
response = http.request(request)
puts response.read_body{
"cluster_name": "products_clip_hdbscan",
"cluster_type": "vector",
"collection_ids": [
"col_products_v1",
"col_products_v2"
],
"llm_labeling": {
"enabled": true,
"labeling_inputs": {
"input_mappings": [
{
"input_key": "text",
"path": "description",
"source_type": "payload"
}
]
},
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
},
"vector_config": {
"clustering_method": "hdbscan",
"feature_uri": "mixpeek://clip_vit_l_14@v1/embedding",
"hdbscan_parameters": {
"min_cluster_size": 10,
"min_samples": 5
},
"sample_size": 5000
}
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Authorizations
Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.
Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.
Path Parameters
Cluster ID or name
Body
application/json
Request model for partially updating a cluster (PATCH operation).
Updated name for the cluster
Updated description for the cluster
Updated metadata for the cluster
Updated LLM labeling configuration. Takes effect on the next POST /v1/clusters/{id}/execute — use this to correct a null labeling_inputs mapping that produced schema-metadata labels, without re-embedding or re-running HDBSCAN.
Show child attributes
Show child attributes
Example:
{
"enabled": true,
"include_keywords": true,
"include_summary": true,
"labeling_inputs": {
"input_mappings": [
{
"input_key": "title",
"path": "title",
"source_type": "payload"
},
{
"input_key": "description",
"path": "description",
"source_type": "payload"
},
{
"input_key": "text",
"path": "text",
"source_type": "payload"
}
]
},
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
}
Updated pre-filter for clustering input documents. Overrides the cluster's stored filter on subsequent execute calls.
Updated post-HDBSCAN face-identity merge configuration. Takes effect on the next POST /v1/clusters/{id}/execute. Pass an object with enabled=false to turn the merge pass off without removing the config; pass null in the patch to leave the stored value untouched.
Show child attributes
Show child attributes
Updated per-execution document cap. Takes effect on the next POST /v1/clusters/{id}/execute. Omit to leave the stored value untouched; set to an integer to change it. KMeans supports up to 1M; O(N²) algorithms are capped at 100K by the engine.
Required range:
x <= 1000000Updated algorithm parameters (e.g. min_cluster_size, min_samples for HDBSCAN). Takes effect on the next POST /v1/clusters/{id}/execute.
Updated layout-stability mode: 'align' keeps the map stable across runs (default behavior), 'transform' reuses the previous run's saved projection when compatible, 'none' re-layouts every run. Takes effect on the next POST /v1/clusters/{id}/execute. Omit to leave the stored value untouched.
Available options:
none, transform, align Response
Successful Response
Cluster metadata stored in MongoDB.
Collections to cluster together
Minimum array length:
1Optional human-friendly name for the clustering job
Optional description of the cluster, stored with it
Additional user-defined metadata for the cluster
Vector or attribute clustering
Available options:
vector, attribute Required when cluster_type is 'vector'
Show child attributes
Show child attributes
Example:
{
"algorithm_params": { "min_cluster_size": 10, "min_samples": 5 },
"clustering_method": "hdbscan",
"feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding",
"sample_size": 1000
}
Required when cluster_type is 'attribute'
Show child attributes
Show child attributes
Example:
{
"attributes": ["category"],
"hierarchical_grouping": false
}
Optional filters to pre-filter documents before clustering (same format as list documents). Applied during the vector store scroll before parquet export. Useful for clustering subsets like: status='active', category='electronics', etc.
Show child attributes
Show child attributes
Optional configuration for LLM-based cluster labeling. When provided with enabled=True, clusters will have semantic labels generated by LLM instead of generic labels like 'Cluster 0'. When not provided or enabled=False, uses fallback labels.
Show child attributes
Show child attributes
Example:
{
"enabled": true,
"include_keywords": true,
"include_summary": true,
"labeling_inputs": {
"input_mappings": [
{
"input_key": "title",
"path": "title",
"source_type": "payload"
},
{
"input_key": "description",
"path": "description",
"source_type": "payload"
},
{
"input_key": "text",
"path": "text",
"source_type": "payload"
}
]
},
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
}
If True, cluster results are written back to source collection(s) in-place instead of creating new output collections. Documents will be enriched with cluster_id, cluster_label, distance_to_centroid, and optionally other metadata. Similar to taxonomy enrichment pattern.
Configuration for source collection enrichment (only used if enrich_source_collection=True). Controls which fields are added to source documents and field naming conventions.
Show child attributes
Show child attributes
Example:
{
"field_mappings": [
{
"source_field": "cluster_id",
"target_field": "category_id"
},
{
"source_field": "cluster_label",
"target_field": "category_name"
},
{
"source_field": "distance_to_centroid",
"target_field": "category_confidence"
}
]
}
Automatically execute this cluster whenever a batch completes on any of its input collections. When True, a ClusterApplicationConfig entry is added to each input collection's cluster_applications field at creation time. The cluster will then auto-trigger after each batch completion (subject to cooldown and document threshold). When False (default), the cluster must be executed manually via the API.
Minimum number of documents required before auto-executing cluster. Only used when auto_execute_on_batch=True. If the collection has fewer documents than this threshold, clustering is skipped.
Minimum time (in seconds) between automatic cluster executions. Only used when auto_execute_on_batch=True. Default: 3600 (1 hour).
Unique cluster identifier
S3 path to parquet files with cluster data
S3 key to members.parquet (if saved)
Number of clusters found
Clustering quality metrics
Show child attributes
Show child attributes
Clustering job status
Available options:
PENDING, QUEUED, IN_PROGRESS, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED, INTERRUPTED, UNKNOWN, SKIPPED, DRAFT, ACTIVE, ARCHIVED, SUSPENDED, DEACTIVATED Associated task ID for clustering job
Run ID of the most recent successful clustering execution. Used to retrieve execution results.
When the cluster was created
When the cluster was last updated
Was this page helpful?