Get Cluster
Retrieve a cluster by ID or name.
Returns cluster metadata including:
- Configuration (cluster_type, algorithm, parameters)
- Output collection information (output_collection_id, output_collection_name)
- Execution results (num_clusters, num_documents_clustered, status)
- Timestamps and metadata
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
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
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.
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.
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 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. For single output: list with one collection ID. For per-feature output: list with one collection ID per feature.
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)
{
"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)
{
"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.)
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 Error message if cluster execution failed. Propagated from TaskService.
Machine-readable failure classification. Same enum as batch failure_category.
timeout, infrastructure, orphaned, pipeline, 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 Qdrant cluster documents. Used to track LLM failures while allowing fallback labels to work.
Additional user-defined metadata