Create benchmark
curl --request POST \
--url https://api.mixpeek.com/v1/retrievers/benchmarks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"benchmark_name": "<string>",
"baseline_retriever_id": "<string>",
"candidate_retriever_ids": [
"<string>"
],
"session_filter": {
"retriever_ids": [
"<string>"
],
"taxonomy_node_ids": [
"<string>"
],
"time_range": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"min_interactions": 1,
"interaction_types": [
"<string>"
],
"sample_strategy": "random",
"interaction_weights": {
"weights": {}
}
},
"session_count": 1000
}
'import requests
url = "https://api.mixpeek.com/v1/retrievers/benchmarks"
payload = {
"benchmark_name": "<string>",
"baseline_retriever_id": "<string>",
"candidate_retriever_ids": ["<string>"],
"session_filter": {
"retriever_ids": ["<string>"],
"taxonomy_node_ids": ["<string>"],
"time_range": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"min_interactions": 1,
"interaction_types": ["<string>"],
"sample_strategy": "random",
"interaction_weights": { "weights": {} }
},
"session_count": 1000
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
benchmark_name: '<string>',
baseline_retriever_id: '<string>',
candidate_retriever_ids: ['<string>'],
session_filter: {
retriever_ids: ['<string>'],
taxonomy_node_ids: ['<string>'],
time_range: {start: '2023-11-07T05:31:56Z', end: '2023-11-07T05:31:56Z'},
min_interactions: 1,
interaction_types: ['<string>'],
sample_strategy: 'random',
interaction_weights: {weights: {}}
},
session_count: 1000
})
};
fetch('https://api.mixpeek.com/v1/retrievers/benchmarks', 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/retrievers/benchmarks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'benchmark_name' => '<string>',
'baseline_retriever_id' => '<string>',
'candidate_retriever_ids' => [
'<string>'
],
'session_filter' => [
'retriever_ids' => [
'<string>'
],
'taxonomy_node_ids' => [
'<string>'
],
'time_range' => [
'start' => '2023-11-07T05:31:56Z',
'end' => '2023-11-07T05:31:56Z'
],
'min_interactions' => 1,
'interaction_types' => [
'<string>'
],
'sample_strategy' => 'random',
'interaction_weights' => [
'weights' => [
]
]
],
'session_count' => 1000
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/retrievers/benchmarks"
payload := strings.NewReader("{\n \"benchmark_name\": \"<string>\",\n \"baseline_retriever_id\": \"<string>\",\n \"candidate_retriever_ids\": [\n \"<string>\"\n ],\n \"session_filter\": {\n \"retriever_ids\": [\n \"<string>\"\n ],\n \"taxonomy_node_ids\": [\n \"<string>\"\n ],\n \"time_range\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"min_interactions\": 1,\n \"interaction_types\": [\n \"<string>\"\n ],\n \"sample_strategy\": \"random\",\n \"interaction_weights\": {\n \"weights\": {}\n }\n },\n \"session_count\": 1000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/retrievers/benchmarks")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"benchmark_name\": \"<string>\",\n \"baseline_retriever_id\": \"<string>\",\n \"candidate_retriever_ids\": [\n \"<string>\"\n ],\n \"session_filter\": {\n \"retriever_ids\": [\n \"<string>\"\n ],\n \"taxonomy_node_ids\": [\n \"<string>\"\n ],\n \"time_range\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"min_interactions\": 1,\n \"interaction_types\": [\n \"<string>\"\n ],\n \"sample_strategy\": \"random\",\n \"interaction_weights\": {\n \"weights\": {}\n }\n },\n \"session_count\": 1000\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/retrievers/benchmarks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"benchmark_name\": \"<string>\",\n \"baseline_retriever_id\": \"<string>\",\n \"candidate_retriever_ids\": [\n \"<string>\"\n ],\n \"session_filter\": {\n \"retriever_ids\": [\n \"<string>\"\n ],\n \"taxonomy_node_ids\": [\n \"<string>\"\n ],\n \"time_range\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"min_interactions\": 1,\n \"interaction_types\": [\n \"<string>\"\n ],\n \"sample_strategy\": \"random\",\n \"interaction_weights\": {\n \"weights\": {}\n }\n },\n \"session_count\": 1000\n}"
response = http.request(request)
puts response.read_body{
"benchmark_id": "<string>",
"benchmark_name": "<string>",
"baseline_retriever_id": "<string>",
"candidate_retriever_ids": [
"<string>"
],
"session_count": 123,
"status": "pending",
"created_at": "2023-11-07T05:31:56Z",
"session_filter": {
"retriever_ids": [
"<string>"
],
"taxonomy_node_ids": [
"<string>"
],
"time_range": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"min_interactions": 1,
"interaction_types": [
"<string>"
],
"sample_strategy": "random",
"interaction_weights": {
"weights": {}
}
},
"results": [
{
"retriever_id": "<string>",
"retriever_name": "<string>",
"pipeline_hash": "<string>",
"metrics": {
"avg_position_delta": -1.5,
"items_demoted": 45,
"items_promoted": 120,
"mean_rank_clicked": 4.2,
"mean_rank_purchased": 2.8,
"ndcg_at_k": {
"5": 0.78,
"10": 0.82,
"20": 0.85
},
"recall_at_k": {
"5": 0.65,
"10": 0.8,
"20": 0.92
},
"sessions_degraded": 210,
"sessions_improved": 580,
"sessions_neutral": 210
},
"latency": {
"p50_ms": 1,
"p90_ms": 1,
"p99_ms": 1,
"mean_ms": 1,
"stage_latencies": {}
},
"failed_sessions": 1,
"taxonomy_deltas": {},
"error_summary": {}
}
],
"comparison": {
"baseline_retriever_id": "<string>",
"comparisons": [
{
"candidate_retriever_id": "<string>",
"ndcg_delta": {},
"recall_delta": {},
"latency_delta_ms": 123,
"p_value": 123,
"confidence_interval": {
"[0]": 123,
"[1]": 123
},
"taxonomy_wins": [
"<string>"
],
"taxonomy_losses": [
"<string>"
]
}
],
"recommendation": "<string>"
},
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"error_message": "<string>"
}{
"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
}Benchmarks
Create benchmark
Create a new benchmark run to compare retriever pipelines. The benchmark will replay historical sessions and measure alignment with observed user behavior.
POST
/
v1
/
retrievers
/
benchmarks
Create benchmark
curl --request POST \
--url https://api.mixpeek.com/v1/retrievers/benchmarks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Namespace: <api-key>' \
--data '
{
"benchmark_name": "<string>",
"baseline_retriever_id": "<string>",
"candidate_retriever_ids": [
"<string>"
],
"session_filter": {
"retriever_ids": [
"<string>"
],
"taxonomy_node_ids": [
"<string>"
],
"time_range": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"min_interactions": 1,
"interaction_types": [
"<string>"
],
"sample_strategy": "random",
"interaction_weights": {
"weights": {}
}
},
"session_count": 1000
}
'import requests
url = "https://api.mixpeek.com/v1/retrievers/benchmarks"
payload = {
"benchmark_name": "<string>",
"baseline_retriever_id": "<string>",
"candidate_retriever_ids": ["<string>"],
"session_filter": {
"retriever_ids": ["<string>"],
"taxonomy_node_ids": ["<string>"],
"time_range": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"min_interactions": 1,
"interaction_types": ["<string>"],
"sample_strategy": "random",
"interaction_weights": { "weights": {} }
},
"session_count": 1000
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
benchmark_name: '<string>',
baseline_retriever_id: '<string>',
candidate_retriever_ids: ['<string>'],
session_filter: {
retriever_ids: ['<string>'],
taxonomy_node_ids: ['<string>'],
time_range: {start: '2023-11-07T05:31:56Z', end: '2023-11-07T05:31:56Z'},
min_interactions: 1,
interaction_types: ['<string>'],
sample_strategy: 'random',
interaction_weights: {weights: {}}
},
session_count: 1000
})
};
fetch('https://api.mixpeek.com/v1/retrievers/benchmarks', 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/retrievers/benchmarks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'benchmark_name' => '<string>',
'baseline_retriever_id' => '<string>',
'candidate_retriever_ids' => [
'<string>'
],
'session_filter' => [
'retriever_ids' => [
'<string>'
],
'taxonomy_node_ids' => [
'<string>'
],
'time_range' => [
'start' => '2023-11-07T05:31:56Z',
'end' => '2023-11-07T05:31:56Z'
],
'min_interactions' => 1,
'interaction_types' => [
'<string>'
],
'sample_strategy' => 'random',
'interaction_weights' => [
'weights' => [
]
]
],
'session_count' => 1000
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/retrievers/benchmarks"
payload := strings.NewReader("{\n \"benchmark_name\": \"<string>\",\n \"baseline_retriever_id\": \"<string>\",\n \"candidate_retriever_ids\": [\n \"<string>\"\n ],\n \"session_filter\": {\n \"retriever_ids\": [\n \"<string>\"\n ],\n \"taxonomy_node_ids\": [\n \"<string>\"\n ],\n \"time_range\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"min_interactions\": 1,\n \"interaction_types\": [\n \"<string>\"\n ],\n \"sample_strategy\": \"random\",\n \"interaction_weights\": {\n \"weights\": {}\n }\n },\n \"session_count\": 1000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/retrievers/benchmarks")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"benchmark_name\": \"<string>\",\n \"baseline_retriever_id\": \"<string>\",\n \"candidate_retriever_ids\": [\n \"<string>\"\n ],\n \"session_filter\": {\n \"retriever_ids\": [\n \"<string>\"\n ],\n \"taxonomy_node_ids\": [\n \"<string>\"\n ],\n \"time_range\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"min_interactions\": 1,\n \"interaction_types\": [\n \"<string>\"\n ],\n \"sample_strategy\": \"random\",\n \"interaction_weights\": {\n \"weights\": {}\n }\n },\n \"session_count\": 1000\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/retrievers/benchmarks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"benchmark_name\": \"<string>\",\n \"baseline_retriever_id\": \"<string>\",\n \"candidate_retriever_ids\": [\n \"<string>\"\n ],\n \"session_filter\": {\n \"retriever_ids\": [\n \"<string>\"\n ],\n \"taxonomy_node_ids\": [\n \"<string>\"\n ],\n \"time_range\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\"\n },\n \"min_interactions\": 1,\n \"interaction_types\": [\n \"<string>\"\n ],\n \"sample_strategy\": \"random\",\n \"interaction_weights\": {\n \"weights\": {}\n }\n },\n \"session_count\": 1000\n}"
response = http.request(request)
puts response.read_body{
"benchmark_id": "<string>",
"benchmark_name": "<string>",
"baseline_retriever_id": "<string>",
"candidate_retriever_ids": [
"<string>"
],
"session_count": 123,
"status": "pending",
"created_at": "2023-11-07T05:31:56Z",
"session_filter": {
"retriever_ids": [
"<string>"
],
"taxonomy_node_ids": [
"<string>"
],
"time_range": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z"
},
"min_interactions": 1,
"interaction_types": [
"<string>"
],
"sample_strategy": "random",
"interaction_weights": {
"weights": {}
}
},
"results": [
{
"retriever_id": "<string>",
"retriever_name": "<string>",
"pipeline_hash": "<string>",
"metrics": {
"avg_position_delta": -1.5,
"items_demoted": 45,
"items_promoted": 120,
"mean_rank_clicked": 4.2,
"mean_rank_purchased": 2.8,
"ndcg_at_k": {
"5": 0.78,
"10": 0.82,
"20": 0.85
},
"recall_at_k": {
"5": 0.65,
"10": 0.8,
"20": 0.92
},
"sessions_degraded": 210,
"sessions_improved": 580,
"sessions_neutral": 210
},
"latency": {
"p50_ms": 1,
"p90_ms": 1,
"p99_ms": 1,
"mean_ms": 1,
"stage_latencies": {}
},
"failed_sessions": 1,
"taxonomy_deltas": {},
"error_summary": {}
}
],
"comparison": {
"baseline_retriever_id": "<string>",
"comparisons": [
{
"candidate_retriever_id": "<string>",
"ndcg_delta": {},
"recall_delta": {},
"latency_delta_ms": 123,
"p_value": 123,
"confidence_interval": {
"[0]": 123,
"[1]": 123
},
"taxonomy_wins": [
"<string>"
],
"taxonomy_losses": [
"<string>"
]
}
],
"recommendation": "<string>"
},
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"error_message": "<string>"
}{
"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.
Body
application/json
Request to create a new benchmark run.
Human-readable name for this benchmark.
Required string length:
1 - 255ID of the baseline retriever pipeline to compare against.
IDs of candidate retriever pipelines to evaluate.
Minimum array length:
1Optional filter criteria for selecting sessions to replay.
Show child attributes
Show child attributes
Number of sessions to include in the benchmark.
Required range:
10 <= x <= 10000Response
Successful Response
Response containing benchmark details and results.
Unique benchmark identifier.
Human-readable name.
Baseline retriever ID.
Candidate retriever IDs.
Number of sessions in benchmark.
Current benchmark status.
Available options:
pending, building_sessions, replaying, computing_metrics, completed, failed Creation timestamp.
Filter criteria used.
Show child attributes
Show child attributes
Results per pipeline (available when completed).
Show child attributes
Show child attributes
Statistical comparison (available when completed).
Show child attributes
Show child attributes
Execution start time.
Completion time.
Error message if failed.
Was this page helpful?