Clusters

Partially Update Cluster

Changed on

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}

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/clusters/{cluster_identifier}
  • Auth: HTTP bearer and API key in header X-Namespace

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.

source_cluster_idsstring[] nullable

Updated source clusters of a composite cluster. Each must be a vector cluster in this namespace with this cluster's feature_uris, and a cluster cannot name itself. The cluster's input collections become the sources' input collections. Takes effect on the next POST /v1/clusters/{id}/execute.

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

Updated layout-stability mode: '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

source_cluster_idsstring[] nullable

Makes this a composite cluster: it groups the centroids of these clusters' runs instead of documents. Each id must be a vector cluster in this namespace with the same feature_uris as this one. Executing a composite cluster without a mode runs mode 'composite' over the newest completed run of each source cluster, one per partition (a partition is a run's filters). Vector clusters only.

cluster_namestring nullable

Optional human-friendly name for the clustering job

descriptionstring nullable

Optional description of the cluster, stored with it

metadataobject

Additional user-defined metadata for the cluster

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

status'PENDING' | 'QUEUED' | 'IN_PROGRESS' | 'PROCESSING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELED' | 'INTERRUPTED' | 'UNKNOWN' | 'SKIPPED' | 'DRAFT' | 'ACTIVE' | 'ARCHIVED' | 'SUSPENDED' | 'DEACTIVATED'

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

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

Changes

  • 24540a9a39c0Revision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

  • 3516cddef582Revision changes
    • warning

      added the new gemini-3.5-flash-lite enum value to the /// response property for the response status

    • info

      added the new gemini-3.5-flash-lite enum value to the request property ///