--- title: "List Cluster Execution History" method: POST path: "/v1/clusters/{cluster_id}/executions/list" tags: ["Cluster Executions"] --- # List Cluster Execution History `POST /v1/clusters/{cluster_id}/executions/list` List execution history for a cluster with pagination, filtering, sorting, and search. Returns all historical executions for the specified cluster, including: - Execution status (pending, processing, completed, failed) - Clustering metrics (silhouette score, Davies-Bouldin index, etc.) - Number of clusters found and documents processed - Execution timestamps and duration - Centroid information Supports: - **Filtering**: Filter by status, date range, metrics, etc. - **Sorting**: Sort by created_at, execution time, metrics - **Search**: Full-text search across execution metadata - **Pagination**: Limit and offset for large result sets Use cases: - View all past executions for a cluster - Compare metrics across runs - Track execution history over time - Debug failed executions - Analyze clustering performance trends ## Path parameters - `cluster_id` string, required — Cluster ID ## Query parameters - `limit` integer, nullable - `page_size` integer, nullable - `offset` integer, nullable - `page` integer, nullable - `cursor` string, nullable - `next_cursor` string, nullable - `after` string, nullable - `include_total` boolean ## Request body - ListClusterExecutionsRequest — Request parameters for listing and filtering cluster execution history. Provides flexible querying of historical clustering executions with filtering, sorting, and search capabilities. Use to build execution history UIs, compare runs over time, and analyze clustering performance trends. Use Cases: - Display execution history table with sorting and filtering - Find failed executions for debugging - Compare metrics across successful runs - Search executions by date range or status - Build execution timeline visualization Query Behavior: - Empty request {} returns all executions sorted by created_at (newest first) - Filters, sort, and search can be combined for complex queries - Results are paginated (use page/page_size query params) Note: All fields are OPTIONAL. Omit for default behavior (all executions, newest first). - `filters` LogicalOperatorInput — Represents a logical operation (AND, OR, NOT) on filter conditions. Allows nesting with a defined depth limit. Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}). - `AND` union[], nullable — Logical AND operation - all conditions must be true - union - LogicalOperatorInput — recursive - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required — Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `value` union, required — Value to compare against - DynamicValue — A value that should be dynamically resolved from the query request. - … - unknown - `OR` union[], nullable — Logical OR operation - at least one condition must be true - union - LogicalOperatorInput — recursive - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required — Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `value` union, required — Value to compare against - DynamicValue — A value that should be dynamically resolved from the query request. - … - unknown - `NOT` union[], nullable — Logical NOT operation - all conditions must be false - union - LogicalOperatorInput — recursive - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against - `field` string, required — Field name to filter on - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `value` union, required — Value to compare against - DynamicValue — A value that should be dynamically resolved from the query request. - … - unknown - `case_sensitive` boolean, nullable — Whether to perform case-sensitive matching - `sort` SortOption — Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending) - `field` string, required — Field to sort by, supports dot notation for nested fields - `direction` 'asc' | 'desc' — Sort direction options. - `search` string, nullable — OPTIONAL. Full-text search query across execution metadata. NOT REQUIRED - omit for no search filtering. Searches in: - run_id: Search by execution identifier. - error_message: Find executions with specific error text. - centroids.label: Search by cluster label names. - centroids.summary: Search by cluster descriptions. Behavior: - Case-insensitive partial matching. - Multiple terms are AND-ed together. - Combines with filters for complex queries. Examples: - 'failed' → Find executions with 'failed' in error messages. - 'product review' → Find executions with clusters about products/reviews. - 'run_abc123' → Find specific execution by ID. ## Response `200` Successful Response - ListClusterExecutionsResponse — Complete response for cluster execution history listing endpoint. Returns paginated execution history with filtering, sorting, and aggregate statistics. Use to build execution history UIs, monitoring dashboards, and performance analytics. Response Structure: - results: Array of execution details (paginated) - pagination: Page navigation info (current page, total pages, etc.) - total_count: Total matching executions (across all pages) - stats: Aggregated metrics for current result set Use Cases: - Build execution history table with pagination - Display execution status dashboard with charts - Monitor clustering performance trends - Debug failed executions - Compare quality metrics across runs Pagination Behavior: - Default: 10 executions per page - Use query params: ?page=1&page_size=20 - results contains current page only - total_count shows all matching executions - pagination provides navigation links Example Workflow: 1. Request: POST /clusters/{id}/executions/list with filters 2. Response: 50 total executions, showing page 1 (10 results) 3. Display: Show 10 results + "Page 1 of 5" + aggregate stats 4. Navigate: Use pagination.next_page for next 10 results - `results` ClusterExecutionResult[], required — REQUIRED. Array of cluster execution results for the current page. Length: 0 to page_size (default 10, max typically 100). Empty array [] if: - No executions exist for this cluster. - Filters matched no results. - Requested page beyond available pages. Sorted by: created_at descending (newest first) by default. Override with sort parameter in request. Each item contains: - run_id: Unique execution identifier. - status: pending/processing/completed/failed. - num_clusters: Clusters found. - metrics: Quality scores (if available). - centroids: Cluster labels and summaries (if available). - created_at/completed_at: Timestamps. - error_message: Error details (if failed). Use for: Rendering execution history table rows. - `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). - `degenerate` union — 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. - boolean - string - `degenerate_detail` string, nullable — 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)'. - `avg_cluster_size` number, nullable — OPTIONAL. Mean number of documents per cluster, noise excluded. - `noise_ratio` number, nullable — 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. - `cluster_size_entropy` number, nullable — 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. - `should_recluster` number, nullable — OPTIONAL. Engine's own advice that this run is worth re-running with different parameters. 0 means no. - `mean_cosine_to_centroid` number, nullable — OPTIONAL. Mean cosine similarity of each clustered point to its own centroid. Higher is tighter. - `min_cosine_to_centroid` number, nullable — 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. - `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' (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 (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. '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). - `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). - `pagination` PaginationResponse, required — PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true - `total` integer, nullable - `page` integer, nullable - `page_size` integer, nullable - `total_pages` integer, nullable - `next_page` string, nullable - `previous_page` string, nullable - `next_cursor` string, nullable - `total_count` integer, required — REQUIRED. Total number of executions matching the query across ALL pages. Use for: - Display total count ('Found 127 executions'). - Calculate pagination ('Showing 1-10 of 127'). - Validate filters (0 = no matches, refine query). Behavior: - Includes all filtered results, not just current page. - Changes when filters are applied. - Equals len(results) only if all results fit on one page. Example: - Query returns 127 executions total. - Page size = 10. - Current page (1) shows results[0:10]. - total_count = 127 (not 10). - `stats` ClusterExecutionListStats — Aggregate statistics calculated across all executions in the current result set. Provides summary metrics for the filtered/searched execution history, useful for dashboards, monitoring, and trend analysis. Statistics are calculated only for the executions returned in the current query (respects filters and pagination). Use Cases: - Display execution summary cards ("5 completed, 2 failed, 3 pending") - Show average execution time trend - Monitor clustering performance over time - Build execution health dashboard - Compare stats across different time periods (via filters) Important: Stats reflect only the current result set, not all historical executions. Apply filters to calculate stats for specific time ranges or statuses. - `total_executions` integer — OPTIONAL (always provided). Total number of executions in current result set. Equals length of results array. Use for: - Display total count in UI ('Showing 10 of 100 executions'). - Validate pagination (total should match page_size × pages). - Check if filters returned any results (0 = no matches). Note: This is the count in the current page, not all executions. - `executions_by_status` object — OPTIONAL (always provided). Count of executions grouped by status. Keys: 'pending', 'processing', 'completed', 'failed'. Values: Number of executions in each status. Use for: - Status distribution chart (pie/bar chart). - Health monitoring (high failed count = problem). - Progress tracking (pending + processing = in-flight jobs). Example: {'completed': 45, 'failed': 3, 'processing': 2, 'pending': 0}. Empty dict {} if no executions in result set. - `avg_execution_time_ms` number — OPTIONAL (always provided). Average execution duration in milliseconds. Calculated as: mean(completed_at - created_at) for completed/failed executions. Excludes pending/processing executions (no completed_at yet). Use for: - Performance monitoring ('Average: 5.2 seconds'). - Trend analysis (is clustering getting slower over time?). - Capacity planning (estimate time for future runs). 0.0 if: No completed/failed executions in result set. Typical values: - Small datasets (< 100 docs): 1000-5000ms (1-5 seconds). - Medium datasets (100-1000 docs): 5000-30000ms (5-30 seconds). - Large datasets (1000+ docs): 30000-300000ms (30 seconds - 5 minutes). - `total_documents_clustered` integer — OPTIONAL (always provided). Total documents processed across all executions. Calculated as: sum(num_points) for all executions in result set. Use for: - Volume tracking ('Processed 10,000 documents'). - Cost estimation (larger datasets = more compute). - Data growth monitoring (compare over time). 0 if: No executions in result set. Note: Same document may be counted multiple times if re-clustered. - `avg_num_clusters` number — OPTIONAL (always provided). Average number of clusters found per execution. Calculated as: mean(num_clusters) for all executions in result set. Use for: - Clustering consistency check (stable avg = consistent results). - Algorithm tuning (avg too high/low may need parameter adjustment). - Trend analysis (is clustering finding more/fewer clusters over time?). 0.0 if: No executions in result set. Typical values: - Under-clustering: < 3 clusters (data may be too diverse). - Good clustering: 3-20 clusters (manageable, meaningful groups). - Over-clustering: > 20 clusters (too granular, hard to interpret). ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error ## Changes - **2026-08-25** `7d35e524d98b` — 8 info - added the optional property `results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/avg_cluster_size` to the response with the `200` status - added the optional property `results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/cluster_size_entropy` to the response with the `200` status - added the optional property `results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/degenerate` to the response with the `200` status - added the optional property `results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/degenerate_detail` to the response with the `200` status - …4 more - **2026-08-09** `5d4c905106b4` — 1 info - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API - **2026-08-02** `72cc17ba6f7f` — 2 info - added the new optional `query` request parameter `after` - added the new optional `query` request parameter `next_cursor` - …earlier changes not shown [Full history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/clusters/:cluster_id/executions/list/post.md) --- [API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/daf60765b81d/schema)