> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Specific Cluster Execution > 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. ## OpenAPI ````yaml get /v1/clusters/{cluster_id}/executions/{run_id} openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: - BearerAuth: [] paths: /v1/clusters/{cluster_id}/executions/{run_id}: get: tags: - Cluster Executions summary: Get Specific Cluster Execution description: |- 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. operationId: >- get_cluster_execution_by_run_v1_clusters__cluster_id__executions__run_id__get parameters: - name: cluster_id in: path required: true schema: type: string description: Cluster ID title: Cluster Id description: Cluster ID - name: run_id in: path required: true schema: type: string description: Run ID title: Run Id description: Run ID - name: include_vectors in: query required: false schema: type: boolean description: >- Include each centroid's embedding vector (centroids[].centroid_vector). Opt-in; see GET /{cluster_id}/executions for details. default: false title: Include Vectors description: >- Include each centroid's embedding vector (centroids[].centroid_vector). Opt-in; see GET /{cluster_id}/executions for details. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ClusterExecutionResult' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] NamespaceHeader: [] components: schemas: ClusterExecutionResult: properties: run_id: type: string pattern: ^run_[a-zA-Z0-9]+$ title: Run Id description: >- 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. examples: - run_a8e270953254754b - run_b3f58210ab - run_xyz789 cluster_id: type: string pattern: ^clust_[a-zA-Z0-9]+$ title: Cluster Id description: >- 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. examples: - clust_ae3e28a429 - clust_xyz789 - clust_abc123 status: type: string enum: - pending - processing - completed - failed - canceled title: Status description: >- 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 or passed its deadline, check error_message for details. 'canceled' = Canceled through the cancel route. Status changes: pending → processing → (completed OR failed), or pending/processing → canceled. Poll this field to track job progress. examples: - completed - processing - pending - failed num_clusters: type: integer minimum: 0 title: Num Clusters description: >- 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. examples: - 3 - 5 - 10 - 25 num_points: type: integer minimum: 0 title: Num Points description: >- 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). examples: - 100 - 1000 - 50000 metrics: anyOf: - $ref: '#/components/schemas/ClusterExecutionMetrics' - type: 'null' description: >- OPTIONAL. Quality metrics evaluating clustering performance. NOT REQUIRED - only present for successful executions. null if: - Execution is still pending/processing. - Execution failed. - Too few points to calculate metrics (need 2+ points). Contains silhouette_score, davies_bouldin_index, calinski_harabasz_score. Use to compare quality across multiple executions. member_counts_stale: type: boolean title: Member Counts Stale description: >- True when member documents were deleted after this run completed, so each centroid's num_members (and member_count on the centroid documents) counts some documents that no longer exist. Re-run the cluster for current counts. default: false centroids: anyOf: - items: $ref: '#/components/schemas/ClusterExecutionCentroid' type: array - type: 'null' title: Centroids description: >- 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. created_at: type: string format: date-time title: Created At description: >- 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. examples: - '2025-11-13T13:20:40.122000Z' - '2025-11-13T10:00:00.000000Z' completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: >- 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. examples: - '2025-11-13T13:25:40.122000Z' - '2025-11-13T10:05:32.456000Z' - null error_message: anyOf: - type: string - type: 'null' title: Error Message description: >- 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. examples: - 'Insufficient documents for clustering: need at least 2 documents' - Feature extractor 'invalid_extractor' not found in collection - 'Clustering algorithm failed: NaN values in embeddings' - null x-mixpeek-redacted: driver_text error_traceback: anyOf: - type: string - type: 'null' title: Error Traceback description: >- 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. x-mixpeek-redacted: driver_text llm_labeling_errors: anyOf: - items: type: string type: array - type: 'null' title: Llm Labeling Errors description: >- 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. examples: - - '{"error": "LLM API timeout", "clusters": ["cl_3", "cl_5"]}' - '{"error": "No representative documents", "clusters": ["cl_1"]}' - - '{"error": "OpenAI rate limit exceeded", "clusters": ["cl_0"]}' - null source_documents: anyOf: - type: integer - type: 'null' title: Source Documents description: >- 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: anyOf: - type: integer - type: 'null' title: Vectors Retrieved description: >- OPTIONAL. Number of vectors the index actually SERVED into the clustering (parquet rows). Below source_documents ⇒ index gap (signature). vectors_clustered: anyOf: - type: integer - type: 'null' title: Vectors Clustered description: >- 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: anyOf: - type: integer - type: 'null' title: Index Gap description: source_documents − vectors_retrieved (>0 = index gap). pipeline_drop: anyOf: - type: integer - type: 'null' title: Pipeline Drop description: vectors_retrieved − vectors_clustered. input_reconciliation_ok: anyOf: - type: boolean - type: 'null' title: Input Reconciliation Ok description: >- 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: anyOf: - items: type: string type: array - type: 'null' title: Input Reconciliation Reasons description: Human-readable descriptions of any reconciliation gaps. pipeline_drop_expected_as_noise: anyOf: - type: boolean - type: 'null' title: Pipeline Drop Expected As Noise description: >- 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: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Label Overrides description: >- 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). examples: - cl_0: Gadget Reviews - null run_name: anyOf: - type: string maxLength: 120 - type: 'null' title: Run Name description: >- 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). examples: - July tuning baseline - null layout_stability_applied: anyOf: - type: string enum: - transform - aligned - none - type: 'null' title: Layout Stability Applied description: >- 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). examples: - aligned - transform - none - null layout_stability_reason: anyOf: - type: string - type: 'null' title: Layout Stability Reason description: >- 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). examples: - aligned to previous run on 412 shared documents - null generation_reap: anyOf: - items: $ref: '#/components/schemas/ClusterGenerationReap' type: array - type: 'null' title: Generation Reap description: >- OPTIONAL. One record per output collection saying what this run did with the previous generation: deleted it, found nothing stale, or kept it (and why). Omitted for executions that predate the record (schema-additive). mode: anyOf: - type: string enum: - full - assign - composite - type: 'null' title: Mode description: >- OPTIONAL. How this execution ran: full, assign, or composite (a clustering of the centroids of earlier executions). Omitted for executions that predate the field. source_execution_ids: anyOf: - items: type: string type: array - type: 'null' title: Source Execution Ids description: >- OPTIONAL. For a composite execution, the source executions (run_id) whose centroids it grouped. Omitted otherwise. composite_mapping: anyOf: - additionalProperties: items: $ref: '#/components/schemas/ClusterCompositeSource' type: array type: object - type: 'null' title: Composite Mapping description: >- OPTIONAL. For a composite execution, each meta-cluster id mapped to the source centroids it holds. A meta-cluster's centroid is the unweighted mean of those source centroids. Omitted otherwise, and for composite executions that predate the field. type: object required: - run_id - cluster_id - status - num_clusters - num_points - created_at title: ClusterExecutionResult description: >- 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. examples: - centroids: - cluster_id: cl_0 keywords: - product - review - quality label: Product Reviews num_members: 45 summary: Customer feedback about products - cluster_id: cl_1 keywords: - help - issue - support label: Support Tickets num_members: 35 summary: Technical support requests - cluster_id: cl_2 keywords: - feature - request - suggestion label: Feature Requests num_members: 20 summary: User feature suggestions cluster_id: clust_ae3e28a429 completed_at: '2025-11-13T13:25:40.122000Z' created_at: '2025-11-13T13:20:40.122000Z' description: Completed execution with excellent metrics metrics: calinski_harabasz_score: 1234.56 davies_bouldin_index: 0.42 silhouette_score: 0.85 num_clusters: 3 num_points: 100 run_id: run_a8e270953254754b status: completed - cluster_id: clust_xyz789 created_at: '2025-11-13T14:00:00.000000Z' description: Execution in progress num_clusters: 0 num_points: 500 run_id: run_b3f58210ab status: processing - cluster_id: clust_abc123 completed_at: '2025-11-13T12:00:05.123000Z' created_at: '2025-11-13T12:00:00.000000Z' description: Failed execution with error details error_message: >- Insufficient documents for clustering: need at least 2 documents, found 1 num_clusters: 0 num_points: 1 run_id: run_xyz789 status: failed ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false ClusterExecutionMetrics: properties: silhouette_score: anyOf: - type: number maximum: 1 minimum: -1 - type: 'null' title: Silhouette Score description: >- 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). examples: - 0.85 - 0.67 - 0.42 - null davies_bouldin_index: anyOf: - type: number minimum: 0 - type: 'null' title: Davies Bouldin Index description: >- 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). examples: - 0.45 - 1.23 - 2.67 - null calinski_harabasz_score: anyOf: - type: number minimum: 0 - type: 'null' title: Calinski Harabasz Score description: >- 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). examples: - 456.78 - 1234.56 - 89.12 - null degenerate: anyOf: - type: boolean - type: string - type: 'null' title: Degenerate description: >- OPTIONAL, THREE-STATE. Whether this clustering carries any information. null/absent = not evaluated. false = evaluated and fine. A reason STRING = evaluated and degenerate, and the string says which kind: 'single_cluster' (one cluster holds every non-noise point), 'all_noise' (nothing was clustered), 'all_singletons' (almost every point is its own cluster), 'dominant_cluster' (more than one cluster, but one holds >=90% of clustered points — note the quality scores above DO compute for this shape, so they describe a near-single grouping and must not be read as evidence of success). Do NOT test this with `is False`: on some surfaces the false state is serialized as 0.0. Test falsiness, or test isinstance(x, str) for the bad case. examples: - false - dominant_cluster - single_cluster - null degenerate_detail: anyOf: - type: string - type: 'null' title: Degenerate Detail description: >- OPTIONAL. Human-readable explanation, present only when `degenerate` is a reason string. Carries the measured fraction, e.g. '1 of 3 cluster(s) holds 99.7% of the 3342 clustered point(s) (0 noise)'. examples: - >- 1 of 3 cluster(s) holds 99.7% of the 3342 clustered point(s) (0 noise) … - null avg_cluster_size: anyOf: - type: number - type: 'null' title: Avg Cluster Size description: OPTIONAL. Mean number of documents per cluster, noise excluded. examples: - 125.4 - null noise_ratio: anyOf: - type: number - type: 'null' title: Noise Ratio description: >- OPTIONAL. Fraction of points the algorithm rejected as noise, 0 to 1. Meaningful only for algorithms that HAVE a noise label (dbscan, hdbscan, optics); kmeans and spectral assign every point and report 0. examples: - 0 - 0.17 - null cluster_size_entropy: anyOf: - type: number - type: 'null' title: Cluster Size Entropy description: >- OPTIONAL. Shannon entropy of the cluster-size distribution. Low entropy with more than one cluster means the sizes are lopsided, which is the same shape `degenerate='dominant_cluster'` flags. examples: - 2.83 - 0.04 - null should_recluster: anyOf: - type: number - type: 'null' title: Should Recluster description: >- OPTIONAL. Engine's own advice that this run is worth re-running with different parameters. 0 means no. examples: - 0 - 1 - null mean_cosine_to_centroid: anyOf: - type: number - type: 'null' title: Mean Cosine To Centroid description: >- OPTIONAL. Mean cosine similarity of each clustered point to its own centroid. Higher is tighter. examples: - 0.81 - null min_cosine_to_centroid: anyOf: - type: number - type: 'null' title: Min Cosine To Centroid description: >- OPTIONAL. Worst cosine similarity of any clustered point to its own centroid. A low value with a high mean means one cluster has a long tail. examples: - 0.12 - null additionalProperties: true type: object title: ClusterExecutionMetrics description: >- 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. examples: - calinski_harabasz_score: 1234.56 davies_bouldin_index: 0.42 description: Excellent clustering quality silhouette_score: 0.85 - calinski_harabasz_score: 678.34 davies_bouldin_index: 0.89 description: Good clustering quality silhouette_score: 0.67 - calinski_harabasz_score: 45.12 davies_bouldin_index: 2.45 description: Poor clustering quality (needs tuning) silhouette_score: 0.23 - description: Metrics not available (failed execution) ClusterExecutionCentroid: properties: cluster_id: type: string minLength: 1 title: Cluster Id description: >- 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. examples: - cl_0 - cl_1 - cl_0_sub_1 - cl_0_sub_1_sub_0 - cl_cluster_noise - cl_-1 - cl_cluster_0 - cl_photonics_2024 num_members: type: integer minimum: 0 title: Num Members description: >- 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). examples: - 150 - 42 - 1 label: anyOf: - type: string - type: 'null' title: Label description: >- 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'. examples: - Product Reviews - Technical Documentation - Customer Support - null summary: anyOf: - type: string - type: 'null' title: Summary description: >- 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. examples: - >- This cluster contains documents related to product reviews and customer feedback. - Technical documentation and API references are grouped here. - null keywords: anyOf: - items: type: string type: array - type: 'null' title: Keywords description: >- 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. examples: - - reviews - products - feedback - - technical - documentation - api - - support - customer - help - null mean_cosine_similarity: anyOf: - type: number - type: 'null' title: Mean Cosine Similarity description: >- Mean cosine similarity of members to centroid (higher = tighter cluster). min_cosine_similarity: anyOf: - type: number - type: 'null' title: Min Cosine Similarity description: >- Minimum cosine similarity of any member to centroid (cluster boundary). centroid_vector: anyOf: - items: type: number type: array - type: 'null' title: Centroid Vector description: >- 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: anyOf: - items: $ref: '#/components/schemas/RepresentativeDocument' type: array - type: 'null' title: Representative Ids description: >- 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' (durability). type: object required: - cluster_id - num_members title: ClusterExecutionCentroid description: |- Centroid information from a clustering execution. Represents a single cluster center from a clustering run, including LLM-generated semantic labels for human understanding. Use Cases: - Display cluster information in dashboards - Show cluster labels and summaries in UI - Group documents by semantic meaning - Filter/search by cluster keywords Note: This model is for execution metadata only (no visualization coordinates). For scatter plot coordinates, use ArtifactCentroid from the artifacts endpoint. examples: - cluster_id: cl_0 description: Cluster with full LLM labeling keywords: - reviews - products - feedback - ratings label: Product Reviews num_members: 150 summary: >- This cluster contains documents related to product reviews and customer feedback. - cluster_id: cl_1 description: Cluster without LLM labeling num_members: 42 - cluster_id: cl_2 description: Small cluster with label keywords: - single - unique - isolation label: Single Member Cluster num_members: 1 summary: This cluster contains only one member. ClusterGenerationReap: properties: output_collection_id: type: string title: Output Collection Id description: The output collection this record is about. decision: type: string enum: - deleted - nothing_stale - skipped_unconfirmed - skipped_unreadable - deleted_late - superseded title: Decision description: >- deleted: the stale prior points were removed. nothing_stale: the new generation rewrote every prior point. skipped_unconfirmed: the store had not durably confirmed the new generation inside the wait, so the prior generation was kept and recorded for a later sweep. deleted_late: that sweep removed them once the store confirmed the write. superseded: a newer run of the cluster completed first, so this record deleted nothing. skipped_unreadable: the prior generation could not be read, so nothing was deleted. pending: type: boolean title: Pending description: >- True while a skipped reap waits for the store to confirm this run's write. default: false partition_key: anyOf: - type: string - type: 'null' title: Partition Key description: The run partition the generation belongs to. superseded_by: anyOf: - type: string - type: 'null' title: Superseded By description: The newer run that superseded a pending reap. finished_at: anyOf: - type: string format: date-time - type: 'null' title: Finished At description: When a pending reap was finished or superseded. prior: anyOf: - type: integer - type: 'null' title: Prior description: >- Points of this cluster run's partition found before the write; null when unreadable. written: type: integer title: Written description: Points this run wrote. stale: type: integer title: Stale description: Prior points the write did not rewrite (candidates). reaped: type: integer title: Reaped description: Points deleted. wal_seq: type: integer title: Wal Seq description: The write's highest store sequence, 0 when the store returned none. default: 0 confirmed_seq: anyOf: - type: integer - type: 'null' title: Confirmed Seq description: >- The store's durable frontier when the run last read it; null when it could not answer. confirmed_unavailable_reason: anyOf: - type: string - type: 'null' title: Confirmed Unavailable Reason description: >- Why the durable frontier could not be read, when it could not. Null on every run that read it. Present because `skipped_unconfirmed` with a null `confirmed_seq` says WHAT happened and not why, and the cause is logged by the cluster driver, whose logs the job's own teardown deletes minutes after it finishes. That is the gap this record exists to close. type: object required: - output_collection_id - decision - written - stale - reaped title: ClusterGenerationReap description: >- What the run did with the PREVIOUS generation of one output collection. A cluster run rewrites its generation (centroid and member documents) and then deletes the prior generation's points it did not rewrite. That delete is fail-closed: it runs only after the store has durably confirmed the new generation, and only when the prior generation could be read. The decision used to live in the Ray driver's log alone, which the job's own teardown removes minutes after it finishes, so a run that kept its old generation (a collection showing two sets of centroids) could not be explained afterwards. This is the durable record. ClusterCompositeSource: properties: source_run_id: type: string title: Source Run Id description: The source execution (run_id) the centroid comes from. original_cluster_id: type: string title: Original Cluster Id description: The centroid's cluster id within that source execution. num_members: type: integer title: Num Members description: Members the source centroid had in its own execution. default: 0 type: object required: - source_run_id - original_cluster_id title: ClusterCompositeSource description: One source centroid a composite meta-cluster groups. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. RepresentativeDocument: properties: document_id: type: string title: Document Id description: Document ID collection_id: anyOf: - type: string - type: 'null' title: Collection Id description: Collection ID for efficient vector filtering type: object required: - document_id title: RepresentativeDocument description: Represents a document used for LLM labeling with collection tracking. securitySchemes: BearerAuth: type: http scheme: bearer description: >- 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. NamespaceHeader: type: apiKey in: header name: X-Namespace description: >- 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`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.