---
title: "Get Clusters"
method: GET
path: "/api/clarity/clusters"
tags: ["clarity"]
---

# Get Clusters

`GET /api/clarity/clusters`

Retrieve user's cluster snapshot.

Called by Clarity MCP server to fetch persisted data for cross-session continuity.
Single-row model: each user has at most one snapshot (enforced by UNIQUE constraint).

Headers:
    X-User-ID: User UUID (required)
    X-Internal-Secret: Internal API secret (required in production)

Returns:
    200: Cluster snapshot data
    401: Missing or malformed X-User-ID header
    403: Invalid internal secret (production only)
    404: No cluster snapshot found for user

Security:
    Validates X-Internal-Secret header to ensure request comes from
    trusted MCP server. In dev mode (INTERNAL_API_SECRET empty), this
    check is skipped.

## Headers

- `X-Internal-Secret` string, nullable
- `X-User-ID` string, nullable

## Response `200`

Successful Response

- GetClusterResponse — Response body for GET /api/clarity/clusters. TIMESTAMP SEMANTICS: created_at is the SNAPSHOT timestamp, reset on each POST. It does NOT represent "first creation time" - each POST is a fresh snapshot. This matches replace-latest semantics (single row per user). updated_at is intentionally omitted (would always equal created_at).
  - `cluster_id` string, uuid, required
  - `cluster_data` object, required
  - `created_at` string, date-time, required
  - `content_hash` string, nullable
  - `thoughts_exhausted` boolean
  - `correctly_clustered` boolean, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/priority-guard/apis/priority-guardian.md) · [All operations](https://skmtc.net/priority-guard/apis/priority-guardian/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/priority-guard/priority-guardian/revisions/8579218b716d/schema)