Update Experiment
curl --request PATCH \
--url https://api.bland.ai/v2/agents/{agent_id}/experiments/{experiment_id} \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"traffic_percentage": 123,
"run_hours": {},
"starts_at": {},
"ends_at": {},
"variant_call_quota": {}
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/experiments/{experiment_id}"
payload = {
"traffic_percentage": 123,
"run_hours": {},
"starts_at": {},
"ends_at": {},
"variant_call_quota": {}
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
traffic_percentage: 123,
run_hours: {},
starts_at: {},
ends_at: {},
variant_call_quota: {}
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/experiments/{experiment_id}', 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/{experiment_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'traffic_percentage' => 123,
'run_hours' => [
],
'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/{experiment_id}"
payload := strings.NewReader("{\n \"traffic_percentage\": 123,\n \"run_hours\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.bland.ai/v2/agents/{agent_id}/experiments/{experiment_id}")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"traffic_percentage\": 123,\n \"run_hours\": {},\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/{experiment_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"traffic_percentage\": 123,\n \"run_hours\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"experiment": {
"id": "f4e3870b-7e35-4088-9855-917de3633c54",
"agent_id": "ff4b135e-2a7e-48e3-9e75-1303718b2f9d",
"status": "active",
"completed_reason": null,
"baseline_env": "production",
"baseline_current_version_id": "41cf1621-96cc-4f7c-8f9c-a8456b65b9fe",
"variant_version_id": "82a83fe3-719f-45f8-9207-4424aac1a26d",
"traffic_percentage": 50,
"run_hours": null,
"starts_at": null,
"ends_at": "2026-10-01T00:00:00.000Z",
"variant_call_quota": 2000,
"variant_calls_routed": 318,
"created_by": "499bd008-10c1-4fb9-841e-87e1961b5904",
"created_at": "2026-09-08T12:40:19.221Z",
"completed_at": null
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "\"variant_version_id\" is not an updatable field (allowed: traffic_percentage, run_hours, starts_at, ends_at, variant_call_quota)"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "Completed experiments cannot be edited"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Experiment not found"
}
]
}
Experiments
Update Experiment
Adjust an active experiment’s split or conditions.
PATCH
/
v2
/
agents
/
{agent_id}
/
experiments
/
{experiment_id}
Update Experiment
curl --request PATCH \
--url https://api.bland.ai/v2/agents/{agent_id}/experiments/{experiment_id} \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"traffic_percentage": 123,
"run_hours": {},
"starts_at": {},
"ends_at": {},
"variant_call_quota": {}
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/experiments/{experiment_id}"
payload = {
"traffic_percentage": 123,
"run_hours": {},
"starts_at": {},
"ends_at": {},
"variant_call_quota": {}
}
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
traffic_percentage: 123,
run_hours: {},
starts_at: {},
ends_at: {},
variant_call_quota: {}
})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/experiments/{experiment_id}', 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/{experiment_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'traffic_percentage' => 123,
'run_hours' => [
],
'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/{experiment_id}"
payload := strings.NewReader("{\n \"traffic_percentage\": 123,\n \"run_hours\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api.bland.ai/v2/agents/{agent_id}/experiments/{experiment_id}")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"traffic_percentage\": 123,\n \"run_hours\": {},\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/{experiment_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"traffic_percentage\": 123,\n \"run_hours\": {},\n \"starts_at\": {},\n \"ends_at\": {},\n \"variant_call_quota\": {}\n}"
response = http.request(request)
puts response.read_body{
"data": {
"experiment": {
"id": "f4e3870b-7e35-4088-9855-917de3633c54",
"agent_id": "ff4b135e-2a7e-48e3-9e75-1303718b2f9d",
"status": "active",
"completed_reason": null,
"baseline_env": "production",
"baseline_current_version_id": "41cf1621-96cc-4f7c-8f9c-a8456b65b9fe",
"variant_version_id": "82a83fe3-719f-45f8-9207-4424aac1a26d",
"traffic_percentage": 50,
"run_hours": null,
"starts_at": null,
"ends_at": "2026-10-01T00:00:00.000Z",
"variant_call_quota": 2000,
"variant_calls_routed": 318,
"created_by": "499bd008-10c1-4fb9-841e-87e1961b5904",
"created_at": "2026-09-08T12:40:19.221Z",
"completed_at": null
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "\"variant_version_id\" is not an updatable field (allowed: traffic_percentage, run_hours, starts_at, ends_at, variant_call_quota)"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "Completed experiments cannot be edited"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Experiment not found"
}
]
}
Overview
Changes an active experiment’s traffic split, schedule, dates, or quota. The variant and baseline are fixed for the experiment’s life; to test a different version, stop it and create a new one. Only the fields below are accepted: any other key returns400 BAD_REQUEST, and so does an empty body. Completed experiments cannot be edited and return 409 CONFLICT, as does a second update that arrives while one is still being applied (retry it).
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.
string
required
The experiment’s unique identifier. Must be a valid UUID; returns
400 BAD_REQUEST otherwise.Body Parameters
Send at least one field. Fields you omit keep their current value.integer
New share of eligible calls routed to the variant,
1 to 100. Use this to ramp the variant up or down.object | null
New weekly schedule, with the same shape and rules as on Create Experiment: an IANA
timezone and a days object keyed mon through sun whose values are { "start": "HH:mm", "end": "HH:mm" } windows. Pass null to remove the schedule and make the variant always eligible.string | null
ISO 8601 datetime before which the variant receives no traffic. Pass
null to clear it.string | null
ISO 8601 datetime at which the experiment completes with
date_ended. Must be in the future and after the effective starts_at (the one in this request, or the stored one if not sent). Pass null to remove the end date.integer | null
New cap on connected variant calls,
1 to 1000000, or null for no cap. Lowering it to or below the current variant_calls_routed completes the experiment immediately with quota_reached, and the response reflects that.Response
object
The experiment after the update.
Show experiment object
Show experiment object
string
Unique identifier for the experiment.
string
The agent the experiment belongs to.
string
active, or completed if the update lowered the quota below the routed count.string | null
null while active; quota_reached if this update completed the experiment.string
The control environment:
production or staging. Not editable.string | null
The version currently pinned to
baseline_env, read at request time.string
The version under test. Not editable.
integer
The current share of eligible calls routed to the variant.
object | null
The current weekly schedule, or
null when 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
The current cap on connected variant calls, or
null for no cap.integer
Connected calls routed to the variant so far.
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": "f4e3870b-7e35-4088-9855-917de3633c54",
"agent_id": "ff4b135e-2a7e-48e3-9e75-1303718b2f9d",
"status": "active",
"completed_reason": null,
"baseline_env": "production",
"baseline_current_version_id": "41cf1621-96cc-4f7c-8f9c-a8456b65b9fe",
"variant_version_id": "82a83fe3-719f-45f8-9207-4424aac1a26d",
"traffic_percentage": 50,
"run_hours": null,
"starts_at": null,
"ends_at": "2026-10-01T00:00:00.000Z",
"variant_call_quota": 2000,
"variant_calls_routed": 318,
"created_by": "499bd008-10c1-4fb9-841e-87e1961b5904",
"created_at": "2026-09-08T12:40:19.221Z",
"completed_at": null
}
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "\"variant_version_id\" is not an updatable field (allowed: traffic_percentage, run_hours, starts_at, ends_at, variant_call_quota)"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "Completed experiments cannot be edited"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Experiment not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?