> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Clusters

![Studio Clusters page listing clusters with algorithm, results, and completion status](https://mintcdn.com/mixpeek/Wd_dr3_jo8gqgFxV/assets/studio/clusters.png?fit=max\&auto=format\&n=Wd_dr3_jo8gqgFxV\&q=85\&s=ef817918dae9ba17f80703bba77b6cac)

The Clusters page — content grouped by similarity, with the algorithm and run status for each cluster.

[Clusters](https://d8ts56gtwtyh1.cloudfront.net/docs/warehouse/clusters.mp4)

Clusters provide warehouse-native grouping, the multimodal equivalent of SQL GROUP BY.

### Create and run clustering jobs

* **Create**: Click New Cluster, select collections, pick vector or attribute clustering, and configure algorithm params. API: [Create Cluster](https://docs.mixpeek.com/docs/api-reference/clusters/create-cluster.md).
* **Execute**: Run the clustering pipeline on the Engine. `mode` picks the run: `full` reclusters everything, `assign` adds new documents to existing centroids, `composite` clusters the centroids of earlier runs. API: [Execute Clustering](https://docs.mixpeek.com/docs/api-reference/clusters/execute-clustering.md).
* **Inspect**: Review centroids, metrics, and members if saved. Under Artifacts, download a run's rows as CSV or Parquet. API: [Export Cluster Run Data](https://docs.mixpeek.com/docs/api-reference/cluster-executions/export-cluster-run-data.md), which takes a `run_id` and returns a presigned download URL.
* **List/Get/Delete**: Manage clustering configurations and results. API: [List](https://docs.mixpeek.com/docs/api-reference/clusters/list-clusters.md), [Get](https://docs.mixpeek.com/docs/api-reference/clusters/get-cluster.md), [Delete](https://docs.mixpeek.com/docs/api-reference/clusters/delete-cluster.md).
* **Browse results**: Read every centroid plus a sample of members, the data behind the scatter plot. API: [Cluster Visualization Data](https://docs.mixpeek.com/docs/api-reference/clusters/cluster-visualization-data.md). For group labels, summaries, and document counts, use [List Cluster Groups](https://docs.mixpeek.com/docs/api-reference/clusters/list-cluster-groups.md).
* **Enrich the source collection**: Create the cluster with `enrich_source_collection` set to true, and each execution writes cluster labels back onto the source documents. API: [Create Cluster](https://docs.mixpeek.com/docs/api-reference/clusters/create-cluster.md).

**Choosing an algorithm at scale.** For collections over \~100K documents, pick a **linear** algorithm — **K-Means**, **Gaussian Mixture**, or **Leiden**. The density/graph algorithms that build a pairwise distance matrix — HDBSCAN, DBSCAN, Agglomerative, Spectral, OPTICS, Mean Shift — do not scale past 100K and will error on larger datasets (an N×N distance matrix at 1M rows would need \~7,000 GB of RAM). To run one of those on a large collection, set a `sample_size` to cluster a representative subset instead. The create-cluster wizard surfaces this guidance inline when you choose the algorithm.

### Visualization

The cluster scatter plot maps reduced coordinates to position and size:

* **x, y** → point position on the chart
* **z** (when `dimension_reduction.components` is `3`) → **dot size**, where larger dots represent higher z-values

This depth-cue approach surfaces the third dimension without requiring a full 3D renderer, making it easy to spot structure that would be lost in a flat 2D projection.

### Tips

* Start with a sample size to validate parameters before full runs.
* Use LLM labeling for human-friendly labels when vectors are dense and unlabeled.
* Set `dimension_reduction.components` to `3` to see depth-based sizing in the scatter plot.

**1. Create a cluster job**

Choose collections and configure algorithm parameters; optionally set dimensionality reduction.

**2. Execute or submit**

Run in real-time or submit as an asynchronous job and track via Tasks.

**3. Inspect and enrich**

Review centroids and metrics. With `enrich_source_collection` on, the execution has already written labels onto the source documents.

Artifacts such as parquet paths allow downstream analytics and reproducible exploration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.