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: <api-key>' \
  --data '
{
  "description": "Get all executions (default behavior)"
}
'

import requests

url = "https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list"

payload = { "description": "Get all executions (default behavior)" }
headers = {
    "Authorization": "Bearer <token>",
    "X-Namespace": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Namespace': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({description: 'Get all executions (default behavior)'})
};

fetch('https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => 'Get all executions (default behavior)'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Namespace: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list"

	payload := strings.NewReader("{\n  \"description\": \"Get all executions (default behavior)\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Namespace", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list")
  .header("Authorization", "Bearer <token>")
  .header("X-Namespace", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Get all executions (default behavior)\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"Get all executions (default behavior)\"\n}"

response = http.request(request)
puts response.read_body

{
  "description": "Typical paginated response with executions",
  "pagination": {
    "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
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

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

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: <api-key>' \
  --data '
{
  "description": "Get all executions (default behavior)"
}
'

import requests

url = "https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list"

payload = { "description": "Get all executions (default behavior)" }
headers = {
    "Authorization": "Bearer <token>",
    "X-Namespace": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Namespace': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({description: 'Get all executions (default behavior)'})
};

fetch('https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => 'Get all executions (default behavior)'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Namespace: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list"

	payload := strings.NewReader("{\n  \"description\": \"Get all executions (default behavior)\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Namespace", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list")
  .header("Authorization", "Bearer <token>")
  .header("X-Namespace", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Get all executions (default behavior)\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/clusters/{cluster_id}/executions/list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"Get all executions (default behavior)\"\n}"

response = http.request(request)
puts response.read_body

{
  "description": "Typical paginated response with executions",
  "pagination": {
    "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
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

Authorizations

Authorization

string

header

required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace

string

header

required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

cluster_id

string

required

Cluster ID

Query Parameters

limit

integer | null

Required range: 1 <= x <= 1000

page_size

integer | null

Required range: 1 <= x <= 1000

offset

integer | null

Required range: 0 <= x <= 10000

page

integer | null

Required range: x >= 1

cursor

string | null

next_cursor

string | null

after

string | null

include_total

boolean

default:false

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

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

filters

LogicalOperator · object | null

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: {AND: [{field: 'status', operator: 'eq', value: 'completed'}]}. - Created in last 7 days: {AND: [{field: 'created_at', operator: 'gte', value: '2025-11-06T00:00:00Z'}]}. - Good quality (silhouette > 0.5): {AND: [{field: 'metrics.silhouette_score', operator: 'gt', value: 0.5}]}. Combine with OR: Status completed OR failed (exclude in-progress).

Show child attributes

sort

SortOption · object | null

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

Show child attributes

string | null

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:

"failed"

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_cursor for the next page; next_page and previous_page are always null (see /docs/platform/pagination)

results

ClusterExecutionResult · object[]

required

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.

Show child attributes

pagination

PaginationResponse · object

required

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_cursor: Opaque cursor for the next page; send it back as the cursor param, and stop paging once it is absent. - next_page, previous_page: Always null. Deprecated; do not use them to decide whether more pages exist (see /docs/platform/pagination). Use for: - Pagination controls ('Page 2 of 5'). - Showing X-Y of Z results calculations.

Show child attributes

total_count

integer

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

Required range: x >= 0

Examples:

127

50

10

0

stats

ClusterExecutionListStats · object | null

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

Show child attributes

Example:

{
  "avg_execution_time_ms": 8234.5,
  "avg_num_clusters": 5.2,
  "executions_by_status": {
    "completed": 45,
    "failed": 3,
    "pending": 0,
    "processing": 2
  },
  "total_documents_clustered": 50000,
  "total_executions": 50
}

Namespaces

Buckets

Collections

Feature Extractors

Documents

Retrievers

Enrich & Improve

Automate

Administer

Advanced

List Cluster Execution History

Authorizations

Path Parameters

Query Parameters

Body

Response