---
title: "POST /entities/embeddings/clusters"
method: POST
path: "/entities/embeddings/clusters"
tags: ["Graph", "Entity"]
---

# POST /entities/embeddings/clusters

`POST /entities/embeddings/clusters`

## Headers

- `X-Authenticated-User-Actor-Id` string, uuid, required

## Request body

- ClusterEntitiesParams
  - `clusterCount` integer, required — Desired number of clusters. Clamped to the number of entities with embeddings when that is smaller.
  - `dimension` integer — Embedding dimension after matryoshka truncation. Must be a positive multiple of 8; values above 512 are rejected. Defaults to 256.
  - `entityIds` EntityId[], required
  - `seed` integer, nullable — Seed for the random number generator used in clustering. If not provided, a random seed will be used.

## Response `200`

Clusters of entities by embedding similarity

- ClusterEntitiesResponse — Result of [`EntityStore::cluster_entities`].
  - `clusters` EntityCluster[], required — One entry per non-empty cluster. Empty clusters (no points assigned) are omitted.
    - `centroid` number[], required — Centroid with length equal to the requested dimension. Typically unit-normalized, but may be the all-zero vector if all assigned points have zero norm.
    - `clusterId` integer, required — Index in `0..min(cluster_count, n)`.
    - `entityIds` EntityId[], required
  - `inertia` number, float, required — Sum of squared chord distances from every clustered entity to its assigned centroid. Lower is tighter; comparable across runs over the same entities, e.g. to choose a cluster count. `0.0` when nothing was clustered.
  - `missingEmbeddings` EntityId[], required — Entities from the request that were not clustered (either because no embedding exists, or because the actor lacks permission to view the entity).

## Other responses

- `422` — Provided request body is invalid
- `500` — Store error occurred

## Changes

- **2026-07-08** `f009c88e8a7f` — 1 info
  - endpoint added
- **2025-04-24** `ccac01e6aad0` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/hashintel/apis/graph/changes/entities/embeddings/clusters/post.md)

---

[API](https://skmtc.dev/hashintel/apis/graph.md) · [All operations](https://skmtc.dev/hashintel/apis/graph/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hashintel/graph/revisions/ba95e69ddba8/schema)