Authorizations
Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.
Headers
REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
"Bearer sk_live_abc123def456"
"Bearer sk_test_xyz789"
REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
"ns_abc123def456"
"production"
"my-namespace"
Path Parameters
Cluster ID
Body
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).
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). 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"}).
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). Specifies how to sort query results.
Attributes: field: Field to sort by direction: Sort direction (ascending or descending)
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.
"failed"
"product review"
"insufficient documents"
"run_abc123"
Response
Successful Response
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
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.
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.
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).
x >= 0127
50
10
0
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). 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.
{
"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
}