curl --request POST \
--url https://api.arize.com/v2/experiments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "My Experiment Name",
"dataset_id": "dataset_12345",
"experiment_runs": [
{
"example_id": "example_001",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 118,
"prompt": "Answer the math question briefly."
},
{
"example_id": "example_002",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 132
},
{
"example_id": "example_003",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 125
}
]
}
'import requests
url = "https://api.arize.com/v2/experiments"
payload = {
"name": "My Experiment Name",
"dataset_id": "dataset_12345",
"experiment_runs": [
{
"example_id": "example_001",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 118,
"prompt": "Answer the math question briefly."
},
{
"example_id": "example_002",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 132
},
{
"example_id": "example_003",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 125
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'My Experiment Name',
dataset_id: 'dataset_12345',
experiment_runs: [
{
example_id: 'example_001',
output: '4',
model: 'gpt-4o-mini',
temperature: 0.2,
latency_ms: 118,
prompt: 'Answer the math question briefly.'
},
{
example_id: 'example_002',
output: '4',
model: 'gpt-4o-mini',
temperature: 0.2,
latency_ms: 132
},
{
example_id: 'example_003',
output: '4',
model: 'gpt-4o-mini',
temperature: 0.2,
latency_ms: 125
}
]
})
};
fetch('https://api.arize.com/v2/experiments', 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.arize.com/v2/experiments",
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([
'name' => 'My Experiment Name',
'dataset_id' => 'dataset_12345',
'experiment_runs' => [
[
'example_id' => 'example_001',
'output' => '4',
'model' => 'gpt-4o-mini',
'temperature' => 0.2,
'latency_ms' => 118,
'prompt' => 'Answer the math question briefly.'
],
[
'example_id' => 'example_002',
'output' => '4',
'model' => 'gpt-4o-mini',
'temperature' => 0.2,
'latency_ms' => 132
],
[
'example_id' => 'example_003',
'output' => '4',
'model' => 'gpt-4o-mini',
'temperature' => 0.2,
'latency_ms' => 125
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.arize.com/v2/experiments"
payload := strings.NewReader("{\n \"name\": \"My Experiment Name\",\n \"dataset_id\": \"dataset_12345\",\n \"experiment_runs\": [\n {\n \"example_id\": \"example_001\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 118,\n \"prompt\": \"Answer the math question briefly.\"\n },\n {\n \"example_id\": \"example_002\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 132\n },\n {\n \"example_id\": \"example_003\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 125\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.arize.com/v2/experiments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"My Experiment Name\",\n \"dataset_id\": \"dataset_12345\",\n \"experiment_runs\": [\n {\n \"example_id\": \"example_001\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 118,\n \"prompt\": \"Answer the math question briefly.\"\n },\n {\n \"example_id\": \"example_002\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 132\n },\n {\n \"example_id\": \"example_003\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 125\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/experiments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"My Experiment Name\",\n \"dataset_id\": \"dataset_12345\",\n \"experiment_runs\": [\n {\n \"example_id\": \"example_001\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 118,\n \"prompt\": \"Answer the math question briefly.\"\n },\n {\n \"example_id\": \"example_002\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 132\n },\n {\n \"example_id\": \"example_003\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 125\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "RXhwZXJpbWVudDoxOmFCY0Q=",
"space_id": "U3BhY2U6MTphQmNE",
"name": "Experiment 1",
"dataset_id": "RGF0YXNldDoxOmFCY0Q=",
"dataset_version_id": "RGF0YXNldFZlcnNpb246MTphQmNE",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-02T12:00:00Z",
"integration_id": null
}{
"status": 400,
"title": "Invalid request parameters",
"detail": "The 'name' field is required and must be a non-empty string.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}{
"status": 401,
"title": "Authentication required",
"detail": "You must be authenticated to access this resource.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}{
"status": 403,
"title": "Access forbidden",
"detail": "You do not have permission to access this resource.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}{
"status": 404,
"title": "Resource not found",
"detail": "The requested resource with ID '12345' was not found.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}{
"status": 409,
"title": "Resource conflict",
"detail": "A resource with the given identifier already exists.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-conflict"
}{
"status": 422,
"title": "Unprocessable Entity",
"detail": "One or more fields failed validation.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}{
"status": 429,
"title": "Rate limit exceeded",
"detail": "You have exceeded the allowed number of requests. Please try again later.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}Create an experiment
Create a new experiment. Empty experiments are not allowed.
An experiment belongs to a space and may optionally be associated with a dataset.
Experiments are composed of “runs”. Each experiment run (JSON object)
must include an output field containing the task’s output. When the
experiment is associated with a dataset, each run must also include an
example_id referencing an example in that dataset.
Payload Requirements
- Provide exactly one of
dataset_idorspace_id. - The
namemust be unique within the dataset it’s associated with, or within the space when it isn’t associated with a dataset, and must not contain double quotes (") or backslashes (\). - Provide at least one run in
experiment_runs. - Each run must include:
output— model/task output for the runexample_id— a correlation ID linking this run to a dataset example. Required only when the experiment is associated with a dataset; its existence in the dataset is never validated.- You may include any additional fields per run that can be used for
analysis or filtering. For example:
model,latency_ms,temperature,prompt,tool_calls, etc.
curl --request POST \
--url https://api.arize.com/v2/experiments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "My Experiment Name",
"dataset_id": "dataset_12345",
"experiment_runs": [
{
"example_id": "example_001",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 118,
"prompt": "Answer the math question briefly."
},
{
"example_id": "example_002",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 132
},
{
"example_id": "example_003",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 125
}
]
}
'import requests
url = "https://api.arize.com/v2/experiments"
payload = {
"name": "My Experiment Name",
"dataset_id": "dataset_12345",
"experiment_runs": [
{
"example_id": "example_001",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 118,
"prompt": "Answer the math question briefly."
},
{
"example_id": "example_002",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 132
},
{
"example_id": "example_003",
"output": "4",
"model": "gpt-4o-mini",
"temperature": 0.2,
"latency_ms": 125
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'My Experiment Name',
dataset_id: 'dataset_12345',
experiment_runs: [
{
example_id: 'example_001',
output: '4',
model: 'gpt-4o-mini',
temperature: 0.2,
latency_ms: 118,
prompt: 'Answer the math question briefly.'
},
{
example_id: 'example_002',
output: '4',
model: 'gpt-4o-mini',
temperature: 0.2,
latency_ms: 132
},
{
example_id: 'example_003',
output: '4',
model: 'gpt-4o-mini',
temperature: 0.2,
latency_ms: 125
}
]
})
};
fetch('https://api.arize.com/v2/experiments', 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.arize.com/v2/experiments",
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([
'name' => 'My Experiment Name',
'dataset_id' => 'dataset_12345',
'experiment_runs' => [
[
'example_id' => 'example_001',
'output' => '4',
'model' => 'gpt-4o-mini',
'temperature' => 0.2,
'latency_ms' => 118,
'prompt' => 'Answer the math question briefly.'
],
[
'example_id' => 'example_002',
'output' => '4',
'model' => 'gpt-4o-mini',
'temperature' => 0.2,
'latency_ms' => 132
],
[
'example_id' => 'example_003',
'output' => '4',
'model' => 'gpt-4o-mini',
'temperature' => 0.2,
'latency_ms' => 125
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.arize.com/v2/experiments"
payload := strings.NewReader("{\n \"name\": \"My Experiment Name\",\n \"dataset_id\": \"dataset_12345\",\n \"experiment_runs\": [\n {\n \"example_id\": \"example_001\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 118,\n \"prompt\": \"Answer the math question briefly.\"\n },\n {\n \"example_id\": \"example_002\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 132\n },\n {\n \"example_id\": \"example_003\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 125\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.arize.com/v2/experiments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"My Experiment Name\",\n \"dataset_id\": \"dataset_12345\",\n \"experiment_runs\": [\n {\n \"example_id\": \"example_001\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 118,\n \"prompt\": \"Answer the math question briefly.\"\n },\n {\n \"example_id\": \"example_002\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 132\n },\n {\n \"example_id\": \"example_003\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 125\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/experiments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"My Experiment Name\",\n \"dataset_id\": \"dataset_12345\",\n \"experiment_runs\": [\n {\n \"example_id\": \"example_001\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 118,\n \"prompt\": \"Answer the math question briefly.\"\n },\n {\n \"example_id\": \"example_002\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 132\n },\n {\n \"example_id\": \"example_003\",\n \"output\": \"4\",\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.2,\n \"latency_ms\": 125\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "RXhwZXJpbWVudDoxOmFCY0Q=",
"space_id": "U3BhY2U6MTphQmNE",
"name": "Experiment 1",
"dataset_id": "RGF0YXNldDoxOmFCY0Q=",
"dataset_version_id": "RGF0YXNldFZlcnNpb246MTphQmNE",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-02T12:00:00Z",
"integration_id": null
}{
"status": 400,
"title": "Invalid request parameters",
"detail": "The 'name' field is required and must be a non-empty string.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}{
"status": 401,
"title": "Authentication required",
"detail": "You must be authenticated to access this resource.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}{
"status": 403,
"title": "Access forbidden",
"detail": "You do not have permission to access this resource.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}{
"status": 404,
"title": "Resource not found",
"detail": "The requested resource with ID '12345' was not found.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}{
"status": 409,
"title": "Resource conflict",
"detail": "A resource with the given identifier already exists.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-conflict"
}{
"status": 422,
"title": "Unprocessable Entity",
"detail": "One or more fields failed validation.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}{
"status": 429,
"title": "Rate limit exceeded",
"detail": "You have exceeded the allowed number of requests. Please try again later.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}Authorizations
Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format
Service accounts may instead present an access token issued by an external identity provider (Microsoft Entra ID) when the account admin has configured that provider. Send it in the same header: Authorization: Bearer <access-token>.
Body
Body containing experiment creation parameters
Experiment creation parameters with an initial set of runs.
An experiment belongs to a space and may optionally be associated with a dataset. Provide exactly one of:
dataset_id— associate the experiment with a dataset; it's created in that dataset's space, and its runs may reference the dataset's examples viaexample_id.space_id— the space to create the experiment in, when it isn't associated with a dataset.
Providing both, or neither, is a validation error.
Response
An experiment object
Experiments combine a dataset (example inputs/expected outputs), a task (the function that produces model outputs), and one or more evaluators (code or LLM judges) to measure performance. Each run is stored independently so you can compare runs, track progress, and validate improvements over time. See the full definition on the Experiments page.
Use an experiment to run tasks on a dataset, attach evaluators to score outputs, and compare runs to confirm improvements.
Was this page helpful?