Sign in
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
}

Changes

Changed in 4 of the 30 revisions of this API.29

  • 7d35e524d98b8See the full diff
    • ○

      added the optional property results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/avg_cluster_size to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/cluster_size_entropy to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/degenerate to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/degenerate_detail to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/mean_cosine_to_centroid to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/min_cosine_to_centroid to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/noise_ratio to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/metrics/anyOf[subschema #1: ClusterExecutionMetrics]/should_recluster to the response with the 200 status

      response-optional-property-added

  • 5d4c905106b41See the full diff
    • ○

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API

      api-security-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 72cc17ba6f7f2See the full diff
    • ○

      added the new optional query request parameter after

      new-optional-request-parameter

    • ○

      added the new optional query request parameter next_cursor

      new-optional-request-parameter

  • 7cb05153331118See the full diff
    • ○

      added the new geo_bounding_box enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/AND/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_bounding_box enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/NOT/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_bounding_box enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/OR/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/AND/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/NOT/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/OR/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/AND/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/NOT/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property filters/anyOf[subschema #1: LogicalOperator]/OR/anyOf[subschema #1]/items/anyOf[subschema #2: FilterCondition]/operator

      request-property-enum-value-added

    • ○

      added the optional property results/items/centroids/anyOf[subschema #1]/items/representative_ids to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/index_gap to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/input_reconciliation_ok to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/input_reconciliation_reasons to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/pipeline_drop to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/pipeline_drop_expected_as_noise to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/source_documents to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/vectors_clustered to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property results/items/vectors_retrieved to the response with the 200 status

      response-optional-property-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog