---
title: "Get Specific Cluster Execution"
method: GET
path: "/v1/clusters/{cluster_id}/executions/{run_id}"
tags: ["Cluster Executions"]
---

# Get Specific Cluster Execution

`GET /v1/clusters/{cluster_id}/executions/{run_id}`

Get a specific execution by run ID.

    Returns detailed execution information for a particular clustering run,
    allowing you to review historical executions and compare results over time.

## Path parameters

- `cluster_id` string, required — Cluster ID
- `run_id` string, required — Run ID

## Query parameters

- `include_vectors` boolean — Include each centroid's embedding vector (centroids[].centroid_vector). Opt-in; see GET /{cluster_id}/executions for details.

## Response `200`

Successful Response

- ClusterExecutionResult — Complete results from a single clustering execution. Represents the outcome of running a clustering algorithm on a collection's documents. Each execution creates a snapshot of clustering results at a point in time, including the clusters found, quality metrics, and semantic labels. Use Cases: - Display clustering execution history in UI - Compare clustering quality across multiple runs - Track execution status for long-running jobs - Debug failed clustering attempts - View cluster summaries and labels for analysis Workflow: 1. Create cluster configuration → POST /clusters 2. Execute clustering → POST /clusters/{id}/execute 3. Poll execution status → GET /clusters/{id}/executions 4. View execution history → POST /clusters/{id}/executions/list Status Lifecycle: pending → processing → completed (or failed) Note: Execution results are immutable once completed. Re-running clustering creates a new execution result with a new run_id.
  - `run_id` string, required — REQUIRED. Unique identifier for this specific clustering execution. Format: 'run_' prefix followed by random alphanumeric string. Used to retrieve specific execution artifacts and results. Each re-execution of the same cluster creates a new run_id. References execution artifacts in S3 and MongoDB.
  - `cluster_id` string, required — REQUIRED. Parent cluster configuration that was executed. Format: 'clust_' prefix followed by random alphanumeric string. Links this execution back to the cluster definition. Multiple executions can share the same cluster_id.
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required — REQUIRED. Current status of the clustering execution. Values: 'pending' = Job queued, waiting to start. 'processing' = Clustering algorithm running (may take minutes for large datasets). 'completed' = Clustering finished successfully, results available. 'failed' = Clustering failed, check error_message for details. Status changes: pending → processing → (completed OR failed). Poll this field to track job progress.
  - `num_clusters` integer, required — REQUIRED. Number of clusters found by the clustering algorithm. Range: 1 to num_points (though typically much lower). Interpretation: Too few clusters = overgeneralization, may need lower n_clusters param. Too many clusters = overfitting, may need higher n_clusters param. Optimal value depends on dataset and use case. Available immediately upon completion, even if metrics fail.
  - `num_points` integer, required — REQUIRED. Total number of documents/points that were clustered. Equals the count of documents in the collection at execution time. Note: This may differ across executions if documents were added/removed. Used to calculate metrics and validate clustering quality. Minimum 2 points required for clustering (1 cluster per point otherwise).
  - `metrics` ClusterExecutionMetrics — Quality metrics for evaluating clustering execution performance. Provides statistical measures to assess the quality of the clustering results. Higher quality clusters have better cohesion (documents within clusters are similar) and separation (clusters are distinct from each other). Use Cases: - Compare quality across multiple clustering executions - Determine optimal number of clusters for a dataset - Validate clustering algorithm performance - Track clustering quality over time - Debug clustering issues (poor metrics indicate problems) Interpretation: - Use silhouette_score as primary quality indicator (0.5+ = good, 0.7+ = excellent) - Lower davies_bouldin_index indicates better-separated clusters - Higher calinski_harabasz_score indicates denser, better-separated clusters Note: All metrics are OPTIONAL and only present if clustering completed successfully. Failed executions return null for all metrics.
    - `silhouette_score` number, nullable — OPTIONAL. Silhouette score measuring cluster cohesion and separation. Range: -1 to +1. Interpretation: +1.0 = Perfect clustering (documents far from other clusters, close to own cluster). 0.0 = Overlapping clusters (documents on cluster boundaries). -1.0 = Poor clustering (documents assigned to wrong clusters). Practical thresholds: 0.7 to 1.0 = Excellent clustering. 0.5 to 0.7 = Good clustering. 0.25 to 0.5 = Weak clustering, consider different parameters. Below 0.25 = Poor clustering, reconfigure or more data needed. null = metric not calculated (too few points or clustering failed).
    - `davies_bouldin_index` number, nullable — OPTIONAL. Davies-Bouldin index measuring cluster separation. Range: 0 to +∞ (lower is better, no upper bound). Interpretation: 0.0 = Perfect separation (impossible in practice). 0.0 to 1.0 = Excellent separation. 1.0 to 2.0 = Good separation. Above 2.0 = Poor separation, clusters overlap. Formula: Average ratio of intra-cluster to inter-cluster distances. Use when: Validating that clusters are distinct and well-separated. null = metric not calculated (too few points or clustering failed).
    - `calinski_harabasz_score` number, nullable — OPTIONAL. Calinski-Harabasz score (also called Variance Ratio Criterion). Range: 0 to +∞ (higher is better, no strict upper bound). Interpretation: Higher values indicate denser, more compact clusters. No universal threshold - compare relative values across runs. Typical good values: 100-1000+ (dataset dependent). Formula: Ratio of between-cluster to within-cluster dispersion. Use when: Comparing different numbers of clusters for the same dataset. Note: Biased toward algorithms that produce spherical, equally-sized clusters. null = metric not calculated (too few points or clustering failed).
  - `centroids` ClusterExecutionCentroid[], nullable — OPTIONAL. List of cluster centroids with semantic labels. NOT REQUIRED - only present for completed executions with LLM labeling enabled. Length: equals num_clusters. Each centroid contains: - cluster_id: Identifier for the cluster (e.g., 'cl_0'). - num_members: Count of documents in this cluster. - label: Human-readable cluster name (e.g., 'Product Reviews'). - summary: Brief description of cluster content. - keywords: Array of representative terms. null if: - Execution pending/processing/failed. - LLM labeling not configured. Use for: Displaying cluster summaries in UI, filtering by cluster.
    - `cluster_id` string, required — REQUIRED. Unique identifier for this cluster within the execution. Vector clustering uses a 'cl_' prefix with a numeric index (e.g., 'cl_0', 'cl_0_sub_1', 'cl_cluster_noise'); attribute clustering uses value-derived IDs (e.g., 'cl_cluster_0' flat, 'cl_photonics_2024' hierarchical). Used to reference this specific cluster in queries and enrichments. Consistent across executions if algorithm deterministic.
    - `num_members` integer, required — REQUIRED. Number of documents/points assigned to this cluster. Indicates cluster size for sizing bubbles in visualizations. Minimum: 1 (K-Means forces assignment). Can be 0 for noise clusters in HDBSCAN (cluster_id = -1).
    - `label` string, nullable — OPTIONAL. Human-readable label generated by LLM (e.g., GPT-4o-mini). Automatically generated when llm_labeling.enabled = true in cluster config. NOT REQUIRED when LLM labeling disabled. Describes the semantic meaning of documents in this cluster. Example: 'Product Reviews', 'Technical Documentation', 'Customer Support'.
    - `summary` string, nullable — OPTIONAL. Detailed description generated by LLM. Automatically generated when llm_labeling.include_summary = true. NOT REQUIRED when LLM labeling disabled or summary not requested. Provides context about what types of documents are in this cluster. Useful for tooltips, expanded views, or detailed explanations.
    - `keywords` string[], nullable — OPTIONAL. List of semantic keywords generated by LLM. Automatically generated when llm_labeling.include_keywords = true. NOT REQUIRED when LLM labeling disabled or keywords not requested. Useful for search, filtering, and quick cluster understanding. Typically 3-5 keywords per cluster.
    - `mean_cosine_similarity` number, nullable — Mean cosine similarity of members to centroid (higher = tighter cluster).
    - `min_cosine_similarity` number, nullable — Minimum cosine similarity of any member to centroid (cluster boundary).
    - `centroid_vector` number[], nullable — OPTIONAL. The cluster centroid's embedding vector. Only populated when a single-execution GET is called with ?include_vectors=true (vectors are large — e.g. 15 centroids x 1024 floats ≈ 120KB — so they're opt-in and never included in execution LIST responses). Enables vector-input searches that use the centroid as the query even when the centroid document is no longer resolvable in the vector store (e.g. artifact-served clusters after a store wipe). Omitted from the response entirely when not requested.
    - `representative_ids` RepresentativeDocument[], nullable — OPTIONAL. Representative documents (document_id + collection_id) offered to the LLM labeler for this cluster, capped upstream to a small sample (~16). Persisted so a labeling failure is diagnosable from the run record alone: absent/empty vs. present-but-unfetchable distinguishes 'no reps were ever selected' from 'reps existed but the fetch/resolution stage failed them' (MC-1128 durability).
      - `document_id` string, required — Document ID
      - `collection_id` string, nullable — Collection ID for efficient vector filtering
  - `created_at` string, date-time, required — REQUIRED. Timestamp when the clustering execution started. ISO 8601 format with timezone (UTC). Used to: - Sort executions chronologically. - Calculate execution duration (completed_at - created_at). - Filter execution history by date range. Always present, even for failed executions.
  - `completed_at` string, date-time, nullable — OPTIONAL. Timestamp when the clustering execution finished. ISO 8601 format with timezone (UTC). NOT REQUIRED - only present for completed or failed executions. null if: status is 'pending' or 'processing'. Use to: - Calculate execution duration (completed_at - created_at). - Show when results became available. Present for both successful and failed executions.
  - `error_message` string, nullable — OPTIONAL. Error message if the clustering execution failed. NOT REQUIRED - only present when status is 'failed'. null if: execution succeeded or is still in progress. Contains: - Human-readable error description. - Possible causes and suggested fixes. - Stack trace details (for debugging). Common errors: - 'Insufficient documents for clustering' (need 2+ docs). - 'Feature extractor not found' (invalid collection config). - 'Out of memory' (dataset too large for algorithm). Use for: Debugging failed executions and user error messages.
  - `error_traceback` string, nullable — OPTIONAL. Tail-truncated Python traceback captured where the execution failed (engine Ray driver or API-side submission). NOT REQUIRED - only present when status is 'failed' and a traceback was captured. null if: execution succeeded, is still in progress, or the failure predates traceback capture. Use for: debugging failed executions when error_message alone (e.g. a raw Ray internals string) is not actionable.
  - `llm_labeling_errors` string[], nullable — OPTIONAL. List of errors encountered during LLM labeling. NOT REQUIRED - only present when LLM labeling was attempted and encountered errors. null if: - LLM labeling was not enabled. - LLM labeling succeeded for all clusters. - Execution is still in progress. Each error is a JSON string containing: - 'error': Human-readable error message. - 'clusters': List of cluster IDs affected by this error. Common errors: - 'LLM API timeout for 2 clusters' (network/API issues). - 'OpenAI rate limit exceeded' (quota exhausted). - 'Invalid model name: gpt-3.5' (config error). - 'No representative documents for cluster cl_3' (empty cluster). Use for: - Debugging why some clusters have fallback labels. - Identifying LLM API issues without failing entire clustering. - Warning users about partial labeling success.
  - `source_documents` integer, nullable — OPTIONAL. Authoritative count of documents in the source collection(s) at cluster time — an INDEPENDENT Mongo count, not derived from the index/parquet path the clustering consumed. 'What SHOULD have clustered.' Compare with vectors_retrieved: a positive index_gap means the index could not serve some documents' vectors, so the result is computed on a biased sample.
  - `vectors_retrieved` integer, nullable — OPTIONAL. Number of vectors the index actually SERVED into the clustering (parquet rows). Below source_documents ⇒ index gap (MI-4159 signature).
  - `vectors_clustered` integer, nullable — OPTIONAL. Number of documents that left the algorithm with a cluster assignment. Below vectors_retrieved for an assign-every-point algorithm ⇒ a silent pipeline drop; for a noise-producing algorithm the gap is expected noise.
  - `index_gap` integer, nullable — source_documents − vectors_retrieved (>0 = index gap).
  - `pipeline_drop` integer, nullable — vectors_retrieved − vectors_clustered.
  - `input_reconciliation_ok` boolean, nullable — OPTIONAL. False when an UNEXPECTED input-count gap was detected (index gap, or a pipeline drop under an assign-every-point algorithm). Expected noise does not set this False.
  - `input_reconciliation_reasons` string[], nullable — Human-readable descriptions of any reconciliation gaps.
  - `pipeline_drop_expected_as_noise` boolean, nullable — OPTIONAL. True when the algorithm legitimately leaves points unassigned (HDBSCAN/DBSCAN/OPTICS/EVoC), so a positive pipeline_drop is expected noise rather than a silent drop.
  - `label_overrides` object, nullable — OPTIONAL. User-applied cluster label renames for this run, keyed by cluster_id (e.g. {'cl_0': 'Gadget Reviews'}). Written via PATCH /v1/clusters/{cluster_id}/executions/{run_id}/labels and persisted on the execution record (per-run, since cluster_ids are per-run) — no re-execution required. When present, centroids[].label and the visualization endpoint's cluster_label fields are already remapped server-side; this map is returned so clients can distinguish user renames from LLM/auto labels. Omitted from the response entirely when no overrides exist (schema-additive).
  - `run_name` string, nullable — OPTIONAL. Human-friendly name for this execution run (e.g. 'July tuning baseline'), set via PATCH /v1/clusters/{cluster_id}/executions/{run_id}/name and persisted on the execution record — no re-execution required. Editable at any time; capped at 120 characters. Use it to tell runs apart in the run selector / execution history instead of raw run_ids. Omitted from the response entirely when the run was never named (schema-additive, same rule as label_overrides).
  - `layout_stability_applied` 'transform' | 'aligned' | 'none', nullable — OPTIONAL. What layout stabilization actually happened on this execution (LS-5). 'transform' = coordinates were projected through the previous run's saved reducer (existing documents pixel-stable). 'aligned' = the fresh layout was registered onto the previous run's coordinates via a least-squares similarity transform over shared documents. 'none' = raw independent layout (stability disabled, first run, or a documented skip — see layout_stability_reason). Omitted for executions that predate LS-5 (schema-additive).
  - `layout_stability_reason` string, nullable — OPTIONAL. Human-readable explanation of layout_stability_applied — e.g. 'aligned to previous run on 412 shared documents' or 'only 3 shared documents with previous run (minimum 20)'. Omitted when absent (schema-additive).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/5d4c905106b4/schema)