Skip to main content
POST
/
v1
/
clusters
/
list
List Clusters
curl --request POST \
  --url https://api.mixpeek.com/v1/clusters/list \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "sort": {
    "field": "created_at",
    "direction": "desc"
  },
  "search": "<string>"
}
'
{
  "results": [
    {
      "cluster_name": "<string>",
      "namespace_id": "<string>",
      "organization_id": "<string>",
      "input_collections": [
        "<string>"
      ],
      "cluster_type": "vector",
      "cluster_id": "<string>",
      "source_bucket_ids": [
        "<string>"
      ],
      "filters": {},
      "feature_uris": [
        "<string>"
      ],
      "multi_feature_strategy": "<string>",
      "learned_weights": {},
      "learning_quality_score": 123,
      "effective_feature_method": "<string>",
      "clustered_attributes": [
        "<string>"
      ],
      "hierarchical_grouping": true,
      "aggregation_method": "<string>",
      "output_collection_ids": [
        "<string>"
      ],
      "output_collection_names": [
        "<string>"
      ],
      "algorithm": "<string>",
      "algorithm_params": {},
      "enrich_source": false,
      "source_enrichment_config": {
        "field_mappings": [
          {
            "source_field": "cluster_id",
            "target_field": "category_id"
          },
          {
            "source_field": "cluster_label",
            "target_field": "category_name"
          },
          {
            "source_field": "distance_to_centroid",
            "target_field": "category_confidence"
          }
        ]
      },
      "llm_labeling": {
        "description": "Text-only labeling with multiple fields",
        "enabled": true,
        "include_keywords": true,
        "include_summary": true,
        "labeling_inputs": {
          "input_mappings": [
            {
              "input_key": "title",
              "path": "title",
              "source_type": "payload"
            },
            {
              "input_key": "description",
              "path": "description",
              "source_type": "payload"
            },
            {
              "input_key": "text",
              "path": "text",
              "source_type": "payload"
            }
          ]
        },
        "model_name": "gpt-4o-mini-2024-07-18",
        "provider": "openai"
      },
      "num_clusters": 123,
      "num_documents_clustered": 123,
      "execution_time_seconds": 123,
      "hierarchy_detected": false,
      "parent_cluster_id": "<string>",
      "child_cluster_ids": [
        "<string>"
      ],
      "hierarchy_relationships": [
        {}
      ],
      "status": "PENDING",
      "last_execution_task_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "last_executed_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "llm_labeling_errors": [
        "<string>"
      ],
      "metadata": {}
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>"
  },
  "total_count": 123,
  "stats": {
    "total_clusters": 0,
    "total_documents": 0,
    "avg_documents_per_cluster": 0,
    "clusters_by_status": {}
  }
}

Headers

Authorization
string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

X-Namespace
string

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Query Parameters

limit
integer | null
offset
integer | null

Body

application/json

Request model for listing clusters.

filters
LogicalOperator · object

Filters to apply when listing clusters

sort
SortOption · object

Sort options for the results

search
string | null

Search query for filtering clusters

Response

Successful Response

Response model for listing clusters.

results
ClusterMetadata · object[]
required

List of cluster metadata

pagination
PaginationResponse · object
required

Pagination information

total_count
integer
required

Total number of clusters matching the query

stats
ClusterListStats · object

Aggregate statistics across all clusters in the result