Get Specific Cluster Execution

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

OPTIONAL. Number of vectors the index actually SERVED into the clustering (parquet rows). Below source_documents ⇒ index gap (signature).

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.

source_documents − vectors_retrieved (>0 = index gap).

vectors_retrieved − vectors_clustered.

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.

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.

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

OPTIONAL. What layout stabilization actually happened on this execution. '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 (schema-additive).

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