---
title: "Cluster Visualization Data"
method: GET
path: "/v1/clusters/{cluster_id}/visualization"
tags: ["Clusters"]
---

# Cluster Visualization Data

`GET /v1/clusters/{cluster_id}/visualization`

Return sampled visualization coordinates for rendering a cluster scatter plot. Returns all centroids plus a random sample of members (default 10,000). Only the fields needed for rendering are returned, keeping the payload small.

## Path parameters

- `cluster_id` string, required — Cluster ID

## Query parameters

- `max_points` integer — Max member points to return
- `centroids_only` boolean — Return only centroid points (fast initial load for large clusters)
- `compact` boolean — Return members as parallel arrays (x[], y[], z[], cluster_ids[], document_ids[]) instead of array-of-objects. ~60% smaller JSON for large point counts. Centroids are still returned as objects.
- `run_id` string — Return the scatter for a SPECIFIC run instead of the current one. The output collection only ever holds the latest run's points, so per-run points are served from that run's stored artifact. Used by Studio's run-compare; omit for the current run (default).

## Response `200`

Successful Response

- unknown

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/04b379bdbb7c/schema)