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.

GET /v1/clusters/{cluster_identifier}

Get Cluster

cURL

curl --request GET \
  --url https://api.mixpeek.com/v1/clusters/{cluster_identifier} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Namespace: <api-key>'

200

{
  "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": {}
}

Authorizations

Authorization · string · header · required

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.

X-Namespace · string · header · required

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_identifier · string · required

Cluster ID or name

Response

200

application/json

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.

cluster_name · string · required

Human-readable cluster name

namespace_id · string · required

Namespace this cluster belongs to

input_collections · string[] · required

Source collection IDs that were clustered

cluster_type · enum<string> · required

Type of clustering: vector (embedding-based) or attribute (metadata-based)

Available options: vector, attribute

cluster_id · string

Unique cluster job identifier

description · string | null

Cluster description

source_cluster_ids · string[] | null

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 · string[] | null

Source bucket IDs that the input collections originated from. Enables bucket lineage tracking.

filters · Filters · object | null

Optional filters that were applied to pre-filter documents before clustering

feature_uris · string[] | null

Feature URIs that were clustered (mixpeek://{extractor}@{version}/{output}). Only for vector clustering.

multi_feature_strategy · string | null

Strategy used if multiple features (concatenate/independent/weighted). Only for vector clustering.

learned_weights · Learned Weights · object | null

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

learning_quality_score · number | null

Clustering quality score from weight learning (e.g., silhouette score). Only populated when multi_feature_strategy='weighted' and weights were learned.

effective_feature_method · string | null

Method for calculating cluster centroids (mean/median/medoid). Only for vector clustering.

face_cluster_merge · FaceClusterMergeConfig · object | null

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

sample_size · integer | null

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.

preprocessing_steps · Preprocessing Steps · object[] | null

Stored preprocessing steps from vector_config. Replayed into ClusteringConfig on every execute.

hierarchical_vector · boolean | null

Whether recursive sub-clustering is enabled for vector clustering.

max_hierarchy_depth · integer | null

Maximum recursion depth for hierarchical sub-clustering.

vis_n_components · enum<integer> | null

Stored visualization dimensionality (2D or 3D). Replayed into ClusteringConfig on every execute as the default.

Available options: 2, 3

layout_stability · enum<string> | null

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).

Available options: none, transform, align

clustered_attributes · string[] | null

Attribute field names that were clustered. Only for attribute clustering.

hierarchical_grouping · boolean | null

Whether hierarchical clustering was used. Only for attribute clustering.

aggregation_method · string | null

Method for aggregating attributes (most_frequent/first/last). Only for attribute clustering.

output_collection_ids · string[]

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.

output_collection_names · string[]

Names of output collections. Corresponds to output_collection_ids.

algorithm · string | null

Clustering algorithm used (hdbscan, kmeans, attribute_based, etc.)

algorithm_params · Algorithm Params · object | null

Algorithm-specific parameters (not used for attribute_based)

enrich_source · boolean · default: false

Whether source documents were enriched with cluster_id

source_enrichment_config · SourceEnrichmentConfig · object | null

Configuration for source enrichment (if enrich_source=True)

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"
    }
  ]
}

llm_labeling · LLMLabeling · object | null

Configuration for LLM-based cluster labeling (applies to all cluster types)

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"
}

num_clusters · integer | null

Number of clusters found (excludes noise/outliers, populated after execution)

num_documents_clustered · integer | null

Total documents processed

execution_time_seconds · number | null

Time taken to complete clustering

quality_metrics · Quality Metrics · object | null

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).

hierarchy_detected · boolean · default: false

Whether implicit hierarchy was detected (multi-feature independent) or created (hierarchical attributes)

parent_cluster_id · string | null

For child clusters in hierarchy

child_cluster_ids · string[] | null

For parent clusters

hierarchy_relationships · Hierarchy Relationships · object[] | null

Parent-child relationships detected from cluster membership overlap

status · enum<string> · default: PENDING

Cluster job status (propagated from TaskService)

Available options: PENDING, QUEUED, IN_PROGRESS, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED, INTERRUPTED, UNKNOWN, SKIPPED, DRAFT, ACTIVE, ARCHIVED, SUSPENDED, DEACTIVATED

error · string | null

Error message if cluster execution failed. Propagated from TaskService.

failure_category · enum<string> | null

Machine-readable failure classification. Same enum as batch failure_category.

Available options: timeout, infrastructure, orphaned, pipeline, mvs_durability, validation, unknown

last_execution_task_id · string | null

Most recent task ID for this cluster

last_run_id · string | null

Most recent execution run ID

created_at · string<date-time>

When cluster was created

updated_at · string<date-time>

When cluster was last updated

last_executed_at · string<date-time> | null

Last execution timestamp

completed_at · string<date-time> | null

When clustering completed successfully

llm_labeling_errors · string[] | null

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.

metadata · Metadata · object

Additional user-defined metadata