Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Cluster Executions

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
post/v1/clusters/{cluster_id}/executions/list

Path parameters

cluster_idstring required

Cluster ID

Cluster ID

Query parameters

limitinteger nullable
page_sizeinteger nullable
offsetinteger nullable
pageinteger nullable
cursorstring nullable
next_cursorstring nullable
afterstring nullable
include_totalboolean

Request body

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

Example request

{
  "description": "Get all executions (default behavior)"
}

Response

Successful Response

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

Example response

{
  "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
}