Create Experiment
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/experiments \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"variant_version_id": "<string>",
"traffic_percentage": 123,
"baseline_env": "<string>",
"run_hours": {},
"run_hours.timezone": "<string>",
"run_hours.days": {},
"starts_at": {},
"ends_at": {},
"variant_call_quota": {}
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/experiments"
payload = {
"variant_version_id": "<string>",
"traffic_percentage": 123,
"baseline_env": "<string>",
"run_hours": {},
"run_hours.timezone": "<string>",
"run_hours.days": {},
"starts_at": {},
"ends_at": {},
"variant_call_quota": {}
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
variant_version_id: '<string>',
traffic_percentage: 123,
baseline_env: '<string>',
run_hours: {},
'run_hours.timezone': '<string>',
'run_hours.days': {},
starts_at: {},
ends_at: {},
variant_call_quota: {}
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/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.bland.ai/v2/agents/{agent_id}/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([
'variant_version_id' => '<string>',
'traffic_percentage' => 123,
'baseline_env' => '<string>',
'run_hours' => [
],
'run_hours.timezone' => '<string>',
'run_hours.days' => [
],
'starts_at' => [
],
'ends_at' => [
],
'variant_call_quota' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$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.bland.ai/v2/agents/{agent_id}/experiments"
payload := strings.NewReader("{\n \"variant_version_id\": \"<string>\",\n \"traffic_percentage\": 123,\n \"baseline_env\": \"<string>\",\n \"run_hours\": {},\n \"run_hours.timezone\": \"<string>\",\n \"run_hours.days\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
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.bland.ai/v2/agents/{agent_id}/experiments")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"variant_version_id\": \"<string>\",\n \"traffic_percentage\": 123,\n \"baseline_env\": \"<string>\",\n \"run_hours\": {},\n \"run_hours.timezone\": \"<string>\",\n \"run_hours.days\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/experiments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"variant_version_id\": \"<string>\",\n \"traffic_percentage\": 123,\n \"baseline_env\": \"<string>\",\n \"run_hours\": {},\n \"run_hours.timezone\": \"<string>\",\n \"run_hours.days\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"experiment": {
"id": "5c590769-b12c-4f5e-8608-85dd2ac29bb1",
"agent_id": "4fdd0f5b-4416-42f6-bb85-fb42d3ceec29",
"status": "active",
"completed_reason": null,
"baseline_env": "production",
"baseline_current_version_id": "d717a103-f912-42f4-ae07-6a2a8b5395b0",
"variant_version_id": "dc7c8387-c78e-4942-8190-b8899f31237d",
"traffic_percentage": 20,
"run_hours": {
"timezone": "America/Chicago",
"days": {
"mon": { "start": "09:00", "end": "17:00" },
"tue": { "start": "09:00", "end": "17:00" },
"wed": { "start": "09:00", "end": "17:00" },
"thu": { "start": "09:00", "end": "17:00" },
"fri": { "start": "09:00", "end": "17:00" }
}
},
"starts_at": null,
"ends_at": "2026-09-24T00:00:00.000Z",
"variant_call_quota": 500,
"variant_calls_routed": 0,
"created_by": "3ba21c4b-2b23-413d-8a09-1ce549a29391",
"created_at": "2026-09-10T20:14:33.508Z",
"completed_at": null
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "traffic_percentage must be an integer between 1 and 100"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "variant_version_id is not a version of this agent"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "This agent already has an active experiment — stop it first"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Experiments
Create Experiment
Start an A/B experiment on a variant version.
POST
/
v2
/
agents
/
{agent_id}
/
experiments
Create Experiment
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/experiments \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"variant_version_id": "<string>",
"traffic_percentage": 123,
"baseline_env": "<string>",
"run_hours": {},
"run_hours.timezone": "<string>",
"run_hours.days": {},
"starts_at": {},
"ends_at": {},
"variant_call_quota": {}
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/experiments"
payload = {
"variant_version_id": "<string>",
"traffic_percentage": 123,
"baseline_env": "<string>",
"run_hours": {},
"run_hours.timezone": "<string>",
"run_hours.days": {},
"starts_at": {},
"ends_at": {},
"variant_call_quota": {}
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
variant_version_id: '<string>',
traffic_percentage: 123,
baseline_env: '<string>',
run_hours: {},
'run_hours.timezone': '<string>',
'run_hours.days': {},
starts_at: {},
ends_at: {},
variant_call_quota: {}
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/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.bland.ai/v2/agents/{agent_id}/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([
'variant_version_id' => '<string>',
'traffic_percentage' => 123,
'baseline_env' => '<string>',
'run_hours' => [
],
'run_hours.timezone' => '<string>',
'run_hours.days' => [
],
'starts_at' => [
],
'ends_at' => [
],
'variant_call_quota' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$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.bland.ai/v2/agents/{agent_id}/experiments"
payload := strings.NewReader("{\n \"variant_version_id\": \"<string>\",\n \"traffic_percentage\": 123,\n \"baseline_env\": \"<string>\",\n \"run_hours\": {},\n \"run_hours.timezone\": \"<string>\",\n \"run_hours.days\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
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.bland.ai/v2/agents/{agent_id}/experiments")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"variant_version_id\": \"<string>\",\n \"traffic_percentage\": 123,\n \"baseline_env\": \"<string>\",\n \"run_hours\": {},\n \"run_hours.timezone\": \"<string>\",\n \"run_hours.days\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/experiments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"variant_version_id\": \"<string>\",\n \"traffic_percentage\": 123,\n \"baseline_env\": \"<string>\",\n \"run_hours\": {},\n \"run_hours.timezone\": \"<string>\",\n \"run_hours.days\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"experiment": {
"id": "5c590769-b12c-4f5e-8608-85dd2ac29bb1",
"agent_id": "4fdd0f5b-4416-42f6-bb85-fb42d3ceec29",
"status": "active",
"completed_reason": null,
"baseline_env": "production",
"baseline_current_version_id": "d717a103-f912-42f4-ae07-6a2a8b5395b0",
"variant_version_id": "dc7c8387-c78e-4942-8190-b8899f31237d",
"traffic_percentage": 20,
"run_hours": {
"timezone": "America/Chicago",
"days": {
"mon": { "start": "09:00", "end": "17:00" },
"tue": { "start": "09:00", "end": "17:00" },
"wed": { "start": "09:00", "end": "17:00" },
"thu": { "start": "09:00", "end": "17:00" },
"fri": { "start": "09:00", "end": "17:00" }
}
},
"starts_at": null,
"ends_at": "2026-09-24T00:00:00.000Z",
"variant_call_quota": 500,
"variant_calls_routed": 0,
"created_by": "3ba21c4b-2b23-413d-8a09-1ce549a29391",
"created_at": "2026-09-10T20:14:33.508Z",
"completed_at": null
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "traffic_percentage must be an integer between 1 and 100"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "variant_version_id is not a version of this agent"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "This agent already has an active experiment — stop it first"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Overview
Starts an A/B experiment that sendstraffic_percentage percent of the agent’s eligible calls to variant_version_id, with the rest running the version pinned to baseline_env. Only calls that do not explicitly select a version or environment are eligible. An agent has at most one active experiment: stop it with Stop Experiment before creating another, or adjust it in place with Update Experiment. Returns 409 CONFLICT while one is active.
An experiment completes on its own when ends_at passes, when variant_call_quota connected variant calls have been routed, or when the baseline environment is repointed to another version (for example by a publish or promote). Completion is permanent, and all eligible traffic returns to the baseline pin.
Requires an admin, owner, operator, or prompter role.
Headers
string
required
Your API key for authentication.
Path Parameters
string
required
The agent’s unique identifier.
Body Parameters
string
required
The version to test. Must be a UUID, a version of this agent, and different from the baseline environment’s current pin. The variant is prepared for live calls before the experiment is created, so a version that cannot run returns
400 BAD_REQUEST here rather than failing on calls.integer
required
Share of eligible calls routed to the variant,
1 to 100. The remainder runs the baseline pin.string
default:"production"
production or staging. The environment whose pinned version is the control arm. Returns 400 BAD_REQUEST if that environment has no pinned version.object | null
default:"null"
Weekly schedule during which the variant receives traffic, evaluated in
timezone at each call so daylight-saving changes are handled automatically. Outside the schedule every eligible call runs the baseline. null means the variant is always eligible.{
"timezone": "America/New_York",
"days": {
"mon": { "start": "09:00", "end": "17:00" },
"tue": { "start": "09:00", "end": "17:00" },
"fri": { "start": "22:00", "end": "02:00" }
}
}
string
required
An IANA timezone name such as
America/Chicago. Returns 400 BAD_REQUEST for an unknown name.object
required
Keyed by
mon, tue, wed, thu, fri, sat, sun, with at least one day. Each value is { "start": "HH:mm", "end": "HH:mm" } in 24-hour time, and start and end must differ. A day that is absent never routes to the variant. When end is earlier than start, the window wraps past midnight into the following day.string | null
default:"null"
ISO 8601 datetime. The variant receives no traffic before this time.
null starts immediately.string | null
default:"null"
ISO 8601 datetime. The experiment completes with
completed_reason: "date_ended" once this time passes. Must be in the future and, when starts_at is set, after it. null means no end date.integer | null
default:"null"
Maximum connected variant calls,
1 to 1000000. The experiment completes with completed_reason: "quota_reached" when the count is reached. Only calls that connect count, so unanswered outbound calls never consume quota. null means no cap.Response
object
The new experiment, in
active status.Show experiment object
Show experiment object
string
Unique identifier for the experiment. Pass it as
{experiment_id} on the other experiment endpoints.string
The agent the experiment belongs to.
string
active on creation. Becomes completed when the experiment ends; completion is terminal.string | null
null while active. On completion, one of manual (stopped through the API), date_ended, quota_reached, or baseline_changed (the baseline environment was repointed).string
The control environment:
production or staging.string | null
The version currently pinned to
baseline_env, read at request time. While the experiment is active this is the control arm.string
The version under test.
integer
Share of eligible calls routed to the variant.
object | null
The weekly schedule as submitted, or
null when the variant is always eligible.string | null
When variant traffic begins, or
null for immediately.string | null
When the experiment completes on its own, or
null for no end date.integer | null
Maximum connected variant calls, or
null for no cap.integer
Connected calls routed to the variant so far. Always
0 on creation; live while active, frozen at completion.string | null
ID of the user who created the experiment, or
null when created with an org-level key.string
ISO 8601 timestamp of creation.
string | null
null while active.null | array
null on success, or a list of error objects if the request failed.{
"data": {
"experiment": {
"id": "5c590769-b12c-4f5e-8608-85dd2ac29bb1",
"agent_id": "4fdd0f5b-4416-42f6-bb85-fb42d3ceec29",
"status": "active",
"completed_reason": null,
"baseline_env": "production",
"baseline_current_version_id": "d717a103-f912-42f4-ae07-6a2a8b5395b0",
"variant_version_id": "dc7c8387-c78e-4942-8190-b8899f31237d",
"traffic_percentage": 20,
"run_hours": {
"timezone": "America/Chicago",
"days": {
"mon": { "start": "09:00", "end": "17:00" },
"tue": { "start": "09:00", "end": "17:00" },
"wed": { "start": "09:00", "end": "17:00" },
"thu": { "start": "09:00", "end": "17:00" },
"fri": { "start": "09:00", "end": "17:00" }
}
},
"starts_at": null,
"ends_at": "2026-09-24T00:00:00.000Z",
"variant_call_quota": 500,
"variant_calls_routed": 0,
"created_by": "3ba21c4b-2b23-413d-8a09-1ce549a29391",
"created_at": "2026-09-10T20:14:33.508Z",
"completed_at": null
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "traffic_percentage must be an integer between 1 and 100"
}
]
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "variant_version_id is not a version of this agent"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "This agent already has an active experiment — stop it first"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?