> ## 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. # List Cluster Execution History > 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 ## OpenAPI ````yaml post /v1/clusters/{cluster_id}/executions/list 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: [] paths: /v1/clusters/{cluster_id}/executions/list: post: tags: - Cluster Executions summary: List Cluster Execution History description: >- 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 operationId: list_cluster_executions_v1_clusters__cluster_id__executions_list_post parameters: - name: cluster_id in: path required: true schema: type: string description: Cluster ID title: Cluster Id description: Cluster ID - name: limit in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Limit - name: page_size in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Page Size - name: offset in: query required: false schema: anyOf: - type: integer maximum: 10000 minimum: 0 - type: 'null' title: Offset - name: page in: query required: false schema: anyOf: - type: integer minimum: 1 - type: 'null' title: Page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor - name: include_total in: query required: false schema: type: boolean default: false title: Include Total requestBody: content: application/json: schema: $ref: '#/components/schemas/ListClusterExecutionsRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListClusterExecutionsResponse' '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: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ListClusterExecutionsRequest: properties: filters: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - type: 'null' description: >- OPTIONAL. Complex filtering conditions for execution history. NOT REQUIRED - omit to return all executions. Structure: Logical operator (AND/OR) with array of conditions. Supported filter fields: - status: Filter by execution status (pending/processing/completed/failed). - created_at: Filter by execution start date (use gte/lte for ranges). - num_clusters: Filter by number of clusters found. - metrics.silhouette_score: Filter by quality threshold. Example filters: - Status is completed: {operator: 'AND', conditions: [{field: 'status', value: 'completed', operator: '=='}]}. - Created in last 7 days: {operator: 'AND', conditions: [{field: 'created_at', operator: 'gte', value: '2025-11-06T00:00:00Z'}]}. - Good quality (silhouette > 0.5): {operator: 'AND', conditions: [{field: 'metrics.silhouette_score', operator: '>', value: 0.5}]}. Combine with OR: Status completed OR failed (exclude in-progress). sort: anyOf: - $ref: '#/components/schemas/SortOption' - type: 'null' description: >- OPTIONAL. Sorting configuration for results. NOT REQUIRED - defaults to created_at descending (newest first). Structure: {field: 'field_name', direction: 'asc' or 'desc'}. Sortable fields: - created_at: Sort by execution start time (default). - completed_at: Sort by execution finish time. - num_clusters: Sort by cluster count. - num_points: Sort by document count. - metrics.silhouette_score: Sort by quality score. - status: Sort by execution status. Common use cases: - Newest first (default): {field: 'created_at', direction: 'desc'}. - Best quality first: {field: 'metrics.silhouette_score', direction: 'desc'}. - Failed executions first: {field: 'status', direction: 'asc'} (alphabetical). search: anyOf: - type: string - type: 'null' title: Search description: >- 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. examples: - failed - product review - insufficient documents - run_abc123 type: object title: ListClusterExecutionsRequest description: >- 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). examples: - description: Get all executions (default behavior) - description: Get only completed executions filters: conditions: - field: status operator: '==' value: completed operator: AND - description: Get failed executions in last 7 days, sorted by date filters: conditions: - field: status operator: '==' value: failed - field: created_at operator: gte value: '2025-11-06T00:00:00Z' operator: AND sort: direction: desc field: created_at - description: Get high-quality executions (silhouette > 0.7) filters: conditions: - field: metrics.silhouette_score operator: '>' value: 0.7 operator: AND sort: direction: desc field: metrics.silhouette_score - description: Search executions mentioning 'product' search: product sort: direction: desc field: created_at ListClusterExecutionsResponse: properties: results: items: $ref: '#/components/schemas/ClusterExecutionResult' type: array title: Results description: >- 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. pagination: $ref: '#/components/schemas/PaginationResponse' description: >- REQUIRED. Pagination metadata for navigating result pages. Contains: - total: Total items across all pages (same as total_count). - page: Current page number (1-indexed). - page_size: Items per page. - total_pages: Total number of pages. - next_page: URL for next page (null if last page). - previous_page: URL for previous page (null if first page). Use for: - Pagination controls ('Page 2 of 5'). - Next/Previous buttons (check null for disabled state). - Showing X-Y of Z results calculations. total_count: type: integer minimum: 0 title: Total Count description: >- 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). examples: - 127 - 50 - 10 - 0 stats: anyOf: - $ref: '#/components/schemas/ClusterExecutionListStats' - type: 'null' description: >- OPTIONAL. Aggregate statistics for executions in current result set. NOT REQUIRED - may be null if stats calculation disabled. Typically always provided for execution listing. Contains: - total_executions: Count in current page. - executions_by_status: Status distribution {'completed': 45, 'failed': 3}. - avg_execution_time_ms: Mean duration. - total_documents_clustered: Sum of all processed documents. - avg_num_clusters: Mean clusters per execution. Use for: - Summary cards above table. - Status pie chart. - Performance metrics dashboard. Note: - Stats calculated for current page only (or all if no pagination). - Respects filters (stats for filtered subset). type: object required: - results - pagination - total_count title: ListClusterExecutionsResponse description: >- 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 examples: - description: Typical paginated response with executions pagination: next_page: /clusters/clust_xyz/executions/list?page=2 page: 1 page_size: 10 total: 127 total_pages: 13 results: - centroids: - cluster_id: cl_0 label: Product Reviews num_members: 45 cluster_id: clust_ae3e28a429 completed_at: '2025-11-13T13:25:40.122000Z' created_at: '2025-11-13T13:20:40.122000Z' metrics: silhouette_score: 0.85 num_clusters: 3 num_points: 100 run_id: run_a8e270953254754b status: completed stats: avg_execution_time_ms: 8234.5 avg_num_clusters: 5.2 executions_by_status: completed: 8 failed: 2 total_documents_clustered: 1000 total_executions: 10 total_count: 127 - description: Empty result (no executions found) pagination: page: 1 page_size: 10 total: 0 total_pages: 0 results: [] stats: avg_execution_time_ms: 0 avg_num_clusters: 0 executions_by_status: {} total_documents_clustered: 0 total_executions: 0 total_count: 0 - description: Last page of results (10 total, 3 on last page) pagination: page: 2 page_size: 5 previous_page: /clusters/clust_xyz/executions/list?page=1 total: 10 total_pages: 2 results: - cluster_id: clust_abc123 completed_at: '2025-11-13T12:05:00.000000Z' created_at: '2025-11-13T12:00:00.000000Z' num_clusters: 5 num_points: 200 run_id: run_xyz789 status: completed stats: avg_execution_time_ms: 12000 avg_num_clusters: 5 executions_by_status: completed: 3 total_documents_clustered: 600 total_executions: 3 total_count: 10 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 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError LogicalOperator-Input: properties: AND: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: And description: Logical AND operation - all conditions must be true example: - field: name operator: eq value: John - field: age operator: gte value: 30 OR: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: Or description: Logical OR operation - at least one condition must be true example: - field: status operator: eq value: active - field: role operator: eq value: admin NOT: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: Not description: Logical NOT operation - all conditions must be false example: - field: department operator: eq value: HR - field: location operator: eq value: remote case_sensitive: anyOf: - type: boolean - type: 'null' title: Case Sensitive description: Whether to perform case-sensitive matching default: false example: true additionalProperties: true type: object title: LogicalOperator description: >- 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"}). SortOption: properties: field: type: string title: Field description: Field to sort by, supports dot notation for nested fields example: created_at direction: $ref: '#/components/schemas/SortDirection' description: Sort direction default: asc example: desc type: object required: - field title: SortOption description: |- Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending) 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 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, check error_message for details. Status changes: pending → processing → (completed OR failed). 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. 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 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 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 PaginationResponse: properties: total: anyOf: - type: integer - type: 'null' title: Total page: anyOf: - type: integer - type: 'null' title: Page page_size: anyOf: - type: integer - type: 'null' title: Page Size total_pages: anyOf: - type: integer - type: 'null' title: Total Pages next_page: anyOf: - type: string - type: 'null' title: Next Page previous_page: anyOf: - type: string - type: 'null' title: Previous Page next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor type: object title: PaginationResponse description: |- PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true ClusterExecutionListStats: properties: total_executions: type: integer minimum: 0 title: Total Executions description: >- 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. default: 0 examples: - 10 - 25 - 100 - 0 executions_by_status: additionalProperties: type: integer type: object title: Executions By Status description: >- 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. examples: - completed: 45 failed: 3 processing: 2 - completed: 100 - {} avg_execution_time_ms: type: number minimum: 0 title: Avg Execution Time Ms description: >- 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). default: 0 examples: - 5234.5 - 12890.3 - 45678.9 - 0 total_documents_clustered: type: integer minimum: 0 title: Total Documents Clustered description: >- 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. default: 0 examples: - 10000 - 50000 - 150000 - 0 avg_num_clusters: type: number minimum: 0 title: Avg Num Clusters description: >- 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). default: 0 examples: - 5.3 - 12.7 - 3 - 0 type: object title: ClusterExecutionListStats description: >- 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. examples: - avg_execution_time_ms: 8234.5 avg_num_clusters: 5.2 description: Healthy execution stats (mostly successful) executions_by_status: completed: 45 failed: 3 pending: 0 processing: 2 total_documents_clustered: 50000 total_executions: 50 - avg_execution_time_ms: 12890.3 avg_num_clusters: 7.5 description: All completed executions executions_by_status: completed: 10 total_documents_clustered: 15000 total_executions: 10 - avg_execution_time_ms: 0 avg_num_clusters: 0 description: Empty result set (no executions) executions_by_status: {} total_documents_clustered: 0 total_executions: 0 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. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError FilterCondition: properties: field: type: string title: Field description: Field name to filter on operator: $ref: '#/components/schemas/FilterOperator' description: Comparison operator default: eq value: anyOf: - $ref: '#/components/schemas/DynamicValue' - {} title: Value description: Value to compare against type: object required: - field - value title: FilterCondition description: |- Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against SortDirection: type: string enum: - asc - desc title: SortDirection description: Sort direction options. 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 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 pattern: ^cl_(-?[0-9]+(_sub_[0-9]+)*|cluster_noise)$ title: Cluster Id description: >- REQUIRED. Unique identifier for this cluster within the execution. Format: 'cl_' prefix followed by numeric index (e.g., 'cl_0', 'cl_1'). 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 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). 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. FilterOperator: type: string enum: - eq - ne - gt - lt - gte - lte - in - nin - contains - starts_with - ends_with - regex - exists - is_null - text - phrase title: FilterOperator description: Supported filter operators across database implementations. DynamicValue: properties: type: type: string const: dynamic title: Type default: dynamic field: type: string title: Field description: >- The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id' examples: - inputs.query_text - filters.AND[0].value type: object required: - field title: DynamicValue description: A value that should be dynamically resolved from the query request. ````