Skip to main content
POST
/
v1
/
clusters
/
{cluster_id}
/
executions
/
list
List Cluster Execution History
curl --request POST \
  --url https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "sort": {
    "field": "created_at",
    "direction": "desc"
  },
  "search": "<string>"
}'
{
  "results": [
    {
      "run_id": "<string>",
      "cluster_id": "<string>",
      "status": "pending",
      "num_clusters": 123,
      "num_points": 123,
      "metrics": {
        "silhouette_score": 123,
        "davies_bouldin_index": 123,
        "calinski_harabasz_score": 123
      },
      "centroids": [
        {
          "cluster_id": "<string>",
          "num_members": 123,
          "label": "<string>",
          "summary": "<string>",
          "keywords": [
            "<string>"
          ]
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "error_message": "<string>"
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>"
  },
  "total_count": 123,
  "stats": {
    "total_executions": 0,
    "executions_by_status": {},
    "avg_execution_time_ms": 0,
    "total_documents_clustered": 0,
    "avg_num_clusters": 0
  }
}

Authorizations

Authorization
string
header
required

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

Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

X-Namespace
string
required

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'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

cluster_id
string
required

Cluster ID

Query Parameters

limit
integer | null
offset
integer | null

Body

application/json

Request model for listing cluster execution history.

filters
object | null

Filters to apply when listing cluster executions 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"}).

sort
object | null

Sort options for the results Specifies how to sort query results.

Attributes: field: Field to sort by direction: Sort direction (ascending or descending)

Search query for filtering executions

Response

Successful Response

Response model for listing cluster execution history.

results
ClusterExecutionResult · object[]
required

List of cluster execution results

pagination
object
required

Pagination information

total_count
integer
required

Total number of executions matching the query

stats
object | null

Aggregate statistics across all executions in the result Aggregate statistics for cluster execution history.