curl --request GET \
--url https://api.mixpeek.com/v1/clusters \
--header 'Authorization: Bearer <token>' \
--header 'X-Namespace: <api-key>'import requests
url = "https://api.mixpeek.com/v1/clusters"
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'X-Namespace': '<api-key>'}
};
fetch('https://api.mixpeek.com/v1/clusters', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/clusters",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/clusters"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mixpeek.com/v1/clusters")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/clusters")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"results": [
{
"cluster_name": "<string>",
"namespace_id": "<string>",
"input_collections": [
"<string>"
],
"cluster_type": "vector",
"cluster_id": "<string>",
"description": "<string>",
"source_bucket_ids": [
"<string>"
],
"filters": {},
"feature_uris": [
"<string>"
],
"multi_feature_strategy": "<string>",
"learned_weights": {},
"learning_quality_score": 123,
"effective_feature_method": "<string>",
"face_cluster_merge": {
"enabled": true,
"centroid_cosine_threshold": 0.55,
"bbox_iou_threshold": 0.4,
"scene_jaccard_threshold": 0.3,
"bbox_field": "bbox",
"frame_field": "frame_number",
"scene_field": "scene_id"
},
"sample_size": 123,
"preprocessing_steps": [
{}
],
"hierarchical_vector": true,
"max_hierarchy_depth": 123,
"vis_n_components": 2,
"layout_stability": "none",
"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": {
"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,
"quality_metrics": {},
"hierarchy_detected": false,
"parent_cluster_id": "<string>",
"child_cluster_ids": [
"<string>"
],
"hierarchy_relationships": [
{}
],
"status": "PENDING",
"error": "<string>",
"failure_category": "timeout",
"last_execution_task_id": "<string>",
"last_run_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>",
"next_cursor": "<string>"
},
"total_count": 123,
"stats": {
"total_clusters": 0,
"total_documents": 0,
"avg_documents_per_cluster": 0,
"clusters_by_status": {}
}
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}List Clusters (GET)
REST-convention listing endpoint. Equivalent to POST /v1/clusters/list
with no filters or sort. Use the POST variant when you need filters,
sort, or search.
curl --request GET \
--url https://api.mixpeek.com/v1/clusters \
--header 'Authorization: Bearer <token>' \
--header 'X-Namespace: <api-key>'import requests
url = "https://api.mixpeek.com/v1/clusters"
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'X-Namespace': '<api-key>'}
};
fetch('https://api.mixpeek.com/v1/clusters', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/clusters",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/clusters"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mixpeek.com/v1/clusters")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/clusters")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"results": [
{
"cluster_name": "<string>",
"namespace_id": "<string>",
"input_collections": [
"<string>"
],
"cluster_type": "vector",
"cluster_id": "<string>",
"description": "<string>",
"source_bucket_ids": [
"<string>"
],
"filters": {},
"feature_uris": [
"<string>"
],
"multi_feature_strategy": "<string>",
"learned_weights": {},
"learning_quality_score": 123,
"effective_feature_method": "<string>",
"face_cluster_merge": {
"enabled": true,
"centroid_cosine_threshold": 0.55,
"bbox_iou_threshold": 0.4,
"scene_jaccard_threshold": 0.3,
"bbox_field": "bbox",
"frame_field": "frame_number",
"scene_field": "scene_id"
},
"sample_size": 123,
"preprocessing_steps": [
{}
],
"hierarchical_vector": true,
"max_hierarchy_depth": 123,
"vis_n_components": 2,
"layout_stability": "none",
"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": {
"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,
"quality_metrics": {},
"hierarchy_detected": false,
"parent_cluster_id": "<string>",
"child_cluster_ids": [
"<string>"
],
"hierarchy_relationships": [
{}
],
"status": "PENDING",
"error": "<string>",
"failure_category": "timeout",
"last_execution_task_id": "<string>",
"last_run_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>",
"next_cursor": "<string>"
},
"total_count": 123,
"stats": {
"total_clusters": 0,
"total_documents": 0,
"avg_documents_per_cluster": 0,
"clusters_by_status": {}
}
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Authorizations
Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.
Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.
Query Parameters
Search query string
1 <= x <= 10001 <= x <= 10000 <= x <= 10000x >= 1Response
Successful Response
Response model for listing clusters.
List of cluster metadata
Show child attributes
Show child attributes
Pagination information
Show child attributes
Show child attributes
Total number of clusters matching the query
Aggregate statistics across all clusters in the result
Show child attributes
Show child attributes
Was this page helpful?

