list_clusters
Description: Discover available clusters by browsing domains. Use this tool to identify cluster IDs before calling find_persons.
Tool Identifier: list_clusters
Input Parameters
| Parameter | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| cluster_ids | array | No | - | Array of strings | Filter by specific cluster IDs |
| cluster_hashes | array | No | - | Array of strings | Filter by specific cluster hashes (stable identifiers that persist across data rebuilds) |
| cluster_names | array | No | - | Valid cluster names | Filter by cluster names (download via tool) |
| domains | array | No | - | Valid cluster domains | Filter by domains (see domain list) |
| include_all | boolean | No | false | - | Retrieve all clusters for discovery |
| limit | number | No | 50 | Min: 5, Max: 10000 | Maximum results to return |
| offset | number | No | 0 | Min: 0 | Number of results to skip for pagination |
| workflow_id | string | No | - | Valid UUID | Workflow session identifier for correlation |
Important: If include_all is false, you must provide at least one filter (cluster_ids, cluster_hashes, cluster_names, or domains).
Best Practice: Use cluster_hash instead of cluster_id for saved queries and targeting expressions. Cluster hashes are stable identifiers that persist across data rebuilds, while cluster IDs may change.
Request Schema:
interface ListClustersParams {
cluster_ids?: string[];
cluster_hashes?: string[];
cluster_names?: string[];
domains?: string[];
include_all?: boolean;
limit?: number;
offset?: number;
workflow_id?: string;
}Output Format
Success Response:
{
clusters: Array<{
cluster_id: string,
cluster_hash: string,
domain: string,
name: string,
value: string,
size: number,
prevalence: number,
skew: number,
member_count: number
}>,
total: number,
returned: number,
has_more: boolean,
next_offset?: number,
tool_trace_id: string,
workflow_id: string
}Response Fields:
| Field | Type | Description |
|---|---|---|
| clusters | array | Array of cluster metadata |
| clusters[].cluster_id | string | Unique cluster identifier |
| clusters[].cluster_hash | string | Stable cluster identifier that persists across data rebuilds. Use for long-lived targeting expressions. |
| clusters[].domain | string | Domain category |
| clusters[].name | string | Human-readable cluster name |
| clusters[].value | string | Specific value within the cluster |
| clusters[].size | number | Number of individuals in this cluster |
| clusters[].prevalence | number | Proportion of total population in this cluster (0-1, where 1.0 = 100%) |
| clusters[].skew | number | Data density correction factor. Values > 1.0 indicate under-representation; < 1.0 indicates over-representation |
| clusters[].member_count | number | Pre-computed count of persons in this cluster (kept for backwards compatibility, same as size) |
| total | number | Total clusters matching the query |
| returned | number | Number of clusters in current response |
| has_more | boolean | Whether more results exist beyond current page |
| next_offset | number | Offset value for next page (only present when has_more is true) |
| tool_trace_id | string | OpenTelemetry trace ID for this tool execution |
| workflow_id | string | Workflow session identifier |
Example Response:
{
"clusters": [
{
"cluster_id": "1000000001",
"cluster_hash": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
"domain": "demographic",
"name": "consumer_intent",
"value": "high intent",
"size": 5234567,
"prevalence": 0.15,
"skew": 1.05,
"member_count": 5234567
},
{
"cluster_id": "1000000002",
"cluster_hash": "e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7",
"domain": "demographic",
"name": "education",
"value": "bachelor degree",
"size": 8901234,
"prevalence": 0.25,
"skew": 0.98,
"member_count": 8901234
}
],
"total": 156,
"returned": 2,
"has_more": true,
"next_offset": 2,
"tool_trace_id": "a1b2c3d4e5f6",
"workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}Error Handling
Error Response Format:
{
"content": [
{
"type": "text",
"text": "Cluster listing failed: <error message>"
}
],
"isError": true
}Common Errors:
- No filters provided when include_all is false: "Must provide at least one filter"
- Limit out of range: "Limit must be between 5 and 10000"
- Service temporarily unavailable: "Request failed - please try again"
Usage Examples
Example 1: Discover demographic clusters
{
"domains": ["demographic"],
"limit": 100
}Example 2: Find specific clusters by name
{
"cluster_names": ["education", "household_income_range"],
"limit": 20
}Example 3: Browse all clusters
{
"include_all": true,
"limit": 1000
}Example 4: Look up specific cluster IDs
{
"cluster_ids": ["1000000001", "1000000002"]
}Example 5: Paginate through results
{
"domains": ["demographic"],
"limit": 50,
"offset": 50
}