curl --request GET \
--url https://api.mixpeek.com/v1/clusters/{cluster_identifier} \
--header 'Authorization: Bearer <token>' \
--header 'X-Namespace: <api-key>'import requests
url = "https://api.mixpeek.com/v1/clusters/{cluster_identifier}"
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'X-Namespace': '<api-key>'}
};
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 => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/clusters/{cluster_identifier}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mixpeek.com/v1/clusters/{cluster_identifier}")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.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::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"cluster_name": "<string>",
"namespace_id": "<string>",
"input_collections": [
"<string>"
],
"cluster_type": "vector",
"cluster_id": "<string>",
"description": "<string>",
"source_cluster_ids": [
"<string>"
],
"source_bucket_ids": [
"<string>"
],
"filters": {},
"feature_uris": [
"<string>"
],
"multi_feature_strategy": "<string>",
"learned_weights": {},
"learning_quality_score": 123,
"effective_feature_method": "<string>",
"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,
"preprocessing_steps": [
{}
],
"hierarchical_vector": true,
"max_hierarchy_depth": 123,
"vis_n_components": 2,
"layout_stability": "none",
"clustered_attributes": [
"<string>"
],
"hierarchical_grouping": true,
"aggregation_method": "<string>",
"output_collection_ids": [
"<string>"
],
"output_collection_names": [
"<string>"
],
"algorithm": "<string>",
"algorithm_params": {},
"enrich_source": false,
"source_enrichment_config": {
"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"
}
]
},
"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"
},
"num_clusters": 123,
"num_documents_clustered": 123,
"execution_time_seconds": 123,
"quality_metrics": {},
"hierarchy_detected": false,
"parent_cluster_id": "<string>",
"child_cluster_ids": [
"<string>"
],
"hierarchy_relationships": [
{}
],
"status": "PENDING",
"error": "<string>",
"failure_category": "timeout",
"last_execution_task_id": "<string>",
"last_run_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"last_executed_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"llm_labeling_errors": [
"<string>"
],
"metadata": {}
}{
"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
}{
"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
}Get Cluster
Retrieve a cluster by ID or name.
Returns cluster metadata including:
- Configuration (cluster_type, algorithm, parameters)
- Output collection information (output_collection_ids, output_collection_names)
- Execution results (num_clusters, num_documents_clustered, status)
- Timestamps and metadata
Per-document cluster assignments are not on this object. They are documents in the output collections listed in output_collection_ids: a member document (is_centroid=false) carries cluster_id, cluster_label and source_document_id. With enrich_source_collection=true they are fields on your source documents.
curl --request GET \
--url https://api.mixpeek.com/v1/clusters/{cluster_identifier} \
--header 'Authorization: Bearer <token>' \
--header 'X-Namespace: <api-key>'import requests
url = "https://api.mixpeek.com/v1/clusters/{cluster_identifier}"
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'X-Namespace': '<api-key>'}
};
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 => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/clusters/{cluster_identifier}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mixpeek.com/v1/clusters/{cluster_identifier}")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.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::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"cluster_name": "<string>",
"namespace_id": "<string>",
"input_collections": [
"<string>"
],
"cluster_type": "vector",
"cluster_id": "<string>",
"description": "<string>",
"source_cluster_ids": [
"<string>"
],
"source_bucket_ids": [
"<string>"
],
"filters": {},
"feature_uris": [
"<string>"
],
"multi_feature_strategy": "<string>",
"learned_weights": {},
"learning_quality_score": 123,
"effective_feature_method": "<string>",
"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,
"preprocessing_steps": [
{}
],
"hierarchical_vector": true,
"max_hierarchy_depth": 123,
"vis_n_components": 2,
"layout_stability": "none",
"clustered_attributes": [
"<string>"
],
"hierarchical_grouping": true,
"aggregation_method": "<string>",
"output_collection_ids": [
"<string>"
],
"output_collection_names": [
"<string>"
],
"algorithm": "<string>",
"algorithm_params": {},
"enrich_source": false,
"source_enrichment_config": {
"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"
}
]
},
"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"
},
"num_clusters": 123,
"num_documents_clustered": 123,
"execution_time_seconds": 123,
"quality_metrics": {},
"hierarchy_detected": false,
"parent_cluster_id": "<string>",
"child_cluster_ids": [
"<string>"
],
"hierarchy_relationships": [
{}
],
"status": "PENDING",
"error": "<string>",
"failure_category": "timeout",
"last_execution_task_id": "<string>",
"last_run_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"last_executed_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"llm_labeling_errors": [
"<string>"
],
"metadata": {}
}{
"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
}{
"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
}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, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.
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
Response
Successful Response
Cluster job metadata stored in MongoDB clusters collection.
This is separate from cluster documents themselves. Tracks job-level configuration, status, and summary statistics.
Supports both vector and attribute clustering with appropriate metadata.
Human-readable cluster name
Namespace this cluster belongs to
Source collection IDs that were clustered
Type of clustering: vector (embedding-based) or attribute (metadata-based)
vector, attribute Unique cluster job identifier
Cluster description
Set on a composite cluster: the clusters whose run centroids it groups. Executing it without a mode runs mode 'composite' over the newest completed run of each source cluster, one per partition.
Source bucket IDs that the input collections originated from. Enables bucket lineage tracking.
Optional filters that were applied to pre-filter documents before clustering
Feature URIs that were clustered (mixpeek://{extractor}@{version}/{output}). Only for vector clustering.
Strategy used if multiple features (concatenate/independent/weighted). Only for vector clustering.
Automatically learned feature weights (when multi_feature_strategy='weighted'). Keys are feature URIs, values are learned weights. Only populated after clustering execution completes.
Show child attributes
Show child attributes
Clustering quality score from weight learning (e.g., silhouette score). Only populated when multi_feature_strategy='weighted' and weights were learned.
Method for calculating cluster centroids (mean/median/medoid). Only for vector clustering.
Stored post-HDBSCAN face-identity merge config. Populated from vector_config.face_cluster_merge at cluster creation and replayed into ClusteringConfig on every execute. Only applies to vector clustering.
Show child attributes
Show child attributes
Stored per-execution document cap. Populated from vector_config.sample_size at cluster creation and replayed into ClusteringConfig on every POST /v1/clusters/{id}/execute so re-runs stay consistent with the original config. When None, the export is uncapped (bounded by the engine's 100,000 safety limit). Only applies to vector clustering.
Stored preprocessing steps from vector_config. Replayed into ClusteringConfig on every execute.
Whether recursive sub-clustering is enabled for vector clustering.
Maximum recursion depth for hierarchical sub-clustering.
Stored visualization dimensionality (2D or 3D). Replayed into ClusteringConfig on every execute as the default.
2, 3 Stored layout-stability mode from vector_config.layout_stability. Replayed into ClusteringConfig on every execute. When unset, executions default to 'align' (keep the map stable across runs via post-hoc registration).
none, transform, align Attribute field names that were clustered. Only for attribute clustering.
Whether hierarchical clustering was used. Only for attribute clustering.
Method for aggregating attributes (most_frequent/first/last). Only for attribute clustering.
Collection IDs where cluster documents are stored. Each holds one centroid document (is_centroid=true) per cluster and one member document (is_centroid=false) per clustered source document. A member carries cluster_id, cluster_label and source_document_id, the ID of the document you clustered, so filter on source_document_id to find a source document's cluster. For single output: list with one collection ID. For per-feature output: list with one collection ID per feature. With enrich_source_collection=true no output collection is created: this lists the source collections, and each source document carries its assignment as fields.
Names of output collections. Corresponds to output_collection_ids.
Clustering algorithm used (hdbscan, kmeans, attribute_based, etc.)
Algorithm-specific parameters (not used for attribute_based)
Whether source documents were enriched with cluster_id
Configuration for source enrichment (if enrich_source=True)
Show child attributes
Show child attributes
{
"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"
}
]
}
Configuration for LLM-based cluster labeling (applies to all cluster types)
Show child attributes
Show child attributes
{
"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"
}
Number of clusters found (excludes noise/outliers, populated after execution)
Total documents processed
Time taken to complete clustering
Clustering quality metrics (silhouette_score, davies_bouldin_score, calinski_harabasz_score, etc.). Open diagnostic bag like ClusteringResult.metrics: mostly numeric, but the three-state degenerate flag (False | reason string) and its prose degenerate_detail are non-numeric, so the value type is Any. A float-only type 400'd every GET on a cluster whose run flagged a degenerate result ('s read-path sibling: the write side persisted the string, this read side then rejected it).
Whether implicit hierarchy was detected (multi-feature independent) or created (hierarchical attributes)
For child clusters in hierarchy
For parent clusters
Parent-child relationships detected from cluster membership overlap
Cluster job status (propagated from TaskService)
PENDING, QUEUED, IN_PROGRESS, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED, INTERRUPTED, UNKNOWN, SKIPPED, DRAFT, ACTIVE, ARCHIVED, SUSPENDED, DEACTIVATED Error message if cluster execution failed. Propagated from TaskService.
Machine-readable failure classification. Same enum as batch failure_category.
timeout, infrastructure, orphaned, pipeline, mvs_durability, validation, unknown Most recent task ID for this cluster
Most recent execution run ID
When cluster was created
When cluster was last updated
Last execution timestamp
When clustering completed successfully
List of errors encountered during LLM labeling (if any). Stored in MongoDB cluster metadata only, NOT in vector store cluster documents. Used to track LLM failures while allowing fallback labels to work.
Additional user-defined metadata
Was this page helpful?

