v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB

Clusters

Partially Update Cluster

This endpoint partially updates a cluster (PATCH operation). Only provided fields will be updated. At minimum, metadata can always be updated. Immutable fields like cluster_id, status, and computed fields cannot be modified.

patch/v1/clusters/{cluster_identifier}

Path parameters

cluster_identifierstring required

Cluster ID or name

Request body

cluster_namestring nullable

Updated name for the cluster

descriptionstring nullable

Updated description for the cluster

metadataobject nullable

Updated metadata for the cluster

filtersobject nullable

Updated pre-filter for clustering input documents. Overrides the cluster's stored filter on subsequent execute calls.

sample_sizeinteger nullable

Updated per-execution document cap. Takes effect on the next POST /v1/clusters/{id}/execute. Omit to leave the stored value untouched; set to an integer to change it. KMeans supports up to 1M; O(N²) algorithms are capped at 100K by the engine.

algorithm_paramsobject nullable

Updated algorithm parameters (e.g. min_cluster_size, min_samples for HDBSCAN). Takes effect on the next POST /v1/clusters/{id}/execute.

layout_stability'none' | 'transform' | 'align' nullable

Updated layout-stability mode (LS-5): 'align' keeps the map stable across runs (default behavior), 'transform' reuses the previous run's saved projection when compatible, 'none' re-layouts every run. Takes effect on the next POST /v1/clusters/{id}/execute. Omit to leave the stored value untouched.

Example request

{
  "llm_labeling": {
    "description": "Text-only labeling with multiple fields",
    "enabled": true,
    "include_keywords": true,
    "include_summary": true,
    "labeling_inputs": {
      "input_mappings": [
        {
          "input_key": "title",
          "path": "title",
          "source_type": "payload"
        },
        {
          "input_key": "description",
          "path": "description",
          "source_type": "payload"
        },
        {
          "input_key": "text",
          "path": "text",
          "source_type": "payload"
        }
      ]
    },
    "model_name": "gpt-4o-mini-2024-07-18",
    "provider": "openai"
  }
}

Response

Successful Response

collection_idsstring[] nullable

Collections to cluster together

cluster_namestring nullable

Optional human-friendly name for the clustering job

cluster_type'vector' | 'attribute'

Type of clustering to perform.

Determines the clustering approach:

vector: Cluster documents by embedding similarity (semantic clustering)
attribute: Cluster documents by metadata attributes (business logic clustering)

Use Cases: vector: - Group semantically similar content - Find content with similar meaning - Organize by topic/theme - Requires vector embeddings

attribute:
    - Group by business attributes (category, brand, status, etc.)
    - Organize by explicit metadata
    - Create hierarchical groupings
    - No embeddings required

enrich_source_collectionboolean

If True, cluster results are written back to source collection(s) in-place instead of creating new output collections. Documents will be enriched with cluster_id, cluster_label, distance_to_centroid, and optionally other metadata. Similar to taxonomy enrichment pattern.

auto_execute_on_batchboolean

Automatically execute this cluster whenever a batch completes on any of its input collections. When True, a ClusterApplicationConfig entry is added to each input collection's cluster_applications field at creation time. The cluster will then auto-trigger after each batch completion (subject to cooldown and document threshold). When False (default), the cluster must be executed manually via the API.

auto_execute_min_documentsinteger nullable

Minimum number of documents required before auto-executing cluster. Only used when auto_execute_on_batch=True. If the collection has fewer documents than this threshold, clustering is skipped.

auto_execute_cooldown_secondsinteger

Minimum time (in seconds) between automatic cluster executions. Only used when auto_execute_on_batch=True. Default: 3600 (1 hour).

cluster_idstring

Unique cluster identifier

parquet_pathstring nullable

S3 path to parquet files with cluster data

members_keystring nullable

S3 key to members.parquet (if saved)

num_clustersinteger nullable

Number of clusters found

Enumeration of task statuses for tracking asynchronous operations.

Task statuses indicate the current state of asynchronous operations like batch processing, object ingestion, clustering, and taxonomy execution.

Status Categories: Operation Statuses: Track progress of async operations Lifecycle Statuses: Track entity state (buckets, collections, namespaces)

Values: PENDING: Task is queued but has not started processing yet IN_PROGRESS: Task is currently being executed PROCESSING: Task is actively processing data (similar to IN_PROGRESS) COMPLETED: Task finished successfully with no errors COMPLETED_WITH_ERRORS: Task finished but some items failed (partial success) FAILED: Task encountered an error and could not complete CANCELED: Task was manually canceled by a user or system UNKNOWN: Task status could not be determined SKIPPED: Task was intentionally skipped DRAFT: Task is in draft state and not yet submitted

ACTIVE: Entity is active and operational (for buckets, collections, etc.)
ARCHIVED: Entity has been archived
SUSPENDED: Entity has been temporarily suspended

Terminal Statuses: COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED are terminal statuses. Once a task reaches these states, it will not transition to another state.

Partial Success Handling: COMPLETED_WITH_ERRORS indicates that the operation completed but some documents/items failed. The task result includes: - List of successful items - List of failed items with error details - Success rate percentage This allows clients to handle partial success scenarios appropriately.

Polling Guidance: - Poll tasks in PENDING, QUEUED, IN_PROGRESS, or PROCESSING states - Stop polling when task reaches COMPLETED, COMPLETED_WITH_ERRORS, FAILED, or CANCELED - Use exponential backoff (1s → 30s) when polling

task_idstring nullable

Associated task ID for clustering job

last_run_idstring nullable

Run ID of the most recent successful clustering execution. Used to retrieve execution results.

created_atstring date-time

When the cluster was created

updated_atstring date-time

When the cluster was last updated

metadataobject

Additional user-defined metadata for the cluster

Example response

{
  "cluster_name": "products_clip_hdbscan",
  "cluster_type": "vector",
  "collection_ids": [
    "col_products_v1",
    "col_products_v2"
  ],
  "llm_labeling": {
    "enabled": true,
    "labeling_inputs": {
      "input_mappings": [
        {
          "input_key": "text",
          "path": "description",
          "source_type": "payload"
        }
      ]
    },
    "model_name": "gpt-4o-mini-2024-07-18",
    "provider": "openai"
  },
  "vector_config": {
    "clustering_method": "hdbscan",
    "feature_uri": "mixpeek://clip_vit_l_14@v1/embedding",
    "hdbscan_parameters": {
      "min_cluster_size": 10,
      "min_samples": 5
    },
    "sample_size": 5000
  }
}