Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Clusters

List Clusters

This endpoint allows you to list clusters.

post/v1/clusters/list

Query parameters

limitinteger nullable
page_sizeinteger nullable
offsetinteger nullable
pageinteger nullable
cursorstring nullable
next_cursorstring nullable
afterstring nullable
include_totalboolean

Request body

limitinteger nullable

Page size. A body value wins over the limit query param.

page_sizeinteger nullable

Alias for limit (page size). If both are given, limit wins.

offsetinteger nullable

Number of results to skip (legacy, use cursor instead). A body value wins over the offset query param.

pageinteger nullable

1-indexed page number. Folds to offset = (page-1) * limit. If both page and offset are given, offset wins.

sortsobject[] nullable

Sort options as a list of {field, direction} — the shape Studio datatables and the retriever list send. The first entry is the primary sort. Takes precedence over the singular sort.

searchstring nullable

Search term for wildcard search across cluster_id, cluster_name, description, and other text fields

Example request

{
  "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"
  }
}

Response

Successful Response

total_countinteger required

Total number of clusters matching the query

Example response

{
  "results": [
    {
      "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"
      }
    }
  ]
}