Create an experiment

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=",
  "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"
}

Experiments

Create an experiment

Create a new experiment. Empty experiments are not allowed.

Experiments are composed of “runs”. Each experiment run (JSON object) must include an example_id field that corresponds to an example in the dataset, and a output field that contains the task’s output for the example (the input).

Payload Requirements

The name must be unique within the target dataset
Provide at least one run in experiment_runs.
Each run must include:
- example_id — the ID of an existing example in the dataset/version
- output — model/task output for that example
- You may include any additional fields per run that can be used for analysis or filtering. For exampple: model, latency_ms, temperature, prompt, tool_calls, etc.

This endpoint is in beta, read more here.

POST

experiments

Create an experiment

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=",
  "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

Authorization

string

header

required

Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format

Body

application/json

Body containing experiment creation parameters

Experiment creation parameters with an initial set of runs.

name

string

required

Name of the experiment

dataset_id

string

required

ID of the dataset to create the experiment for

experiment_runs

object[]

required

Array of experiment run data

Show child attributes

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.

string

required

Unique identifier for the experiment

name

string

required

Name of the experiment

created_at

string<date-time>

required

Timestamp for when the experiment was created

updated_at

string<date-time>

required

Timestamp for the last update of the experiment

dataset_id

string | null

Unique identifier for the dataset associated with this experiment. Null if the experiment isn't associated with a dataset.

dataset_version_id

string | null

Unique identifier for the dataset version associated with this experiment. Null if the experiment isn't associated with a dataset.

experiment_traces_project_id

string

Unique identifier for the experiment traces project this experiment belongs to (if it exists)

integration_id

string | null

Identifier (base64) of the agent integration that backs this experiment, as returned by the integrations API. Null for non-agent experiments (for example, SDK or Playground experiments).

List experiments Get an experiment

⌘I

API reference

API clients

Create an experiment

Authorizations

Body

Response