Start Check Run
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/check-runs \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"version_id": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/check-runs"
payload = { "version_id": "<string>" }
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({version_id: '<string>'})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/check-runs', 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}/environments/{env}/check-runs",
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([
'version_id' => '<string>'
]),
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}/environments/{env}/check-runs"
payload := strings.NewReader("{\n \"version_id\": \"<string>\"\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}/environments/{env}/check-runs")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"version_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/check-runs")
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 \"version_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "e8b994db-eeaa-4948-a4b8-3edbca49ca9c",
"agent_id": "9b97c1a6-3171-4139-b83d-b9119586080d",
"env_type": "production",
"agent_version_id": "b7a09422-c97c-49d8-b66f-8991b14e8253",
"semver": "1.4.0",
"version_name": "Shorter greeting",
"status": "PENDING",
"judge_names": ["Resolution quality", "No policy violations"],
"scenario_count": 2,
"simulations_count": 5,
"overall_passed": null,
"verdicts": null,
"simulation_set_id": null,
"eval_run_id": null,
"error_message": null,
"triggered_by": "c43222b9-b7ab-4823-950d-517ac22291ff",
"created_at": "2026-09-10T17:02:39.115Z",
"started_at": null,
"completed_at": null
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "No checks are configured for this environment"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "A check run is already in progress"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Checks
Start Check Run
Start a check run against a candidate version.
POST
/
v2
/
agents
/
{agent_id}
/
environments
/
{env}
/
check-runs
Start Check Run
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/check-runs \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"version_id": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/check-runs"
payload = { "version_id": "<string>" }
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({version_id: '<string>'})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/check-runs', 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}/environments/{env}/check-runs",
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([
'version_id' => '<string>'
]),
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}/environments/{env}/check-runs"
payload := strings.NewReader("{\n \"version_id\": \"<string>\"\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}/environments/{env}/check-runs")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"version_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/environments/{env}/check-runs")
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 \"version_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "e8b994db-eeaa-4948-a4b8-3edbca49ca9c",
"agent_id": "9b97c1a6-3171-4139-b83d-b9119586080d",
"env_type": "production",
"agent_version_id": "b7a09422-c97c-49d8-b66f-8991b14e8253",
"semver": "1.4.0",
"version_name": "Shorter greeting",
"status": "PENDING",
"judge_names": ["Resolution quality", "No policy violations"],
"scenario_count": 2,
"simulations_count": 5,
"overall_passed": null,
"verdicts": null,
"simulation_set_id": null,
"eval_run_id": null,
"error_message": null,
"triggered_by": "c43222b9-b7ab-4823-950d-517ac22291ff",
"created_at": "2026-09-10T17:02:39.115Z",
"started_at": null,
"completed_at": null
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "No checks are configured for this environment"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "A check run is already in progress"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Overview
Starts a check run for one environment. The server generatessimulations_count conversations per configured scenario against the candidate version, scores each with the configured judges, and records a verdict. The run is returned immediately as PENDING, moves to RUNNING, and ends PASSED, FAILED, ERROR, or CANCELLED. Poll Get Check Run until the status is terminal, then gate your own publish or promote call on overall_passed. A check run never moves an environment pointer.
The run freezes the config as it stands when it starts; later edits with Set Checks do not affect it. One run at a time per environment. 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
staging or production. Any other value returns 400 BAD_REQUEST.Body Parameters
string
The version to score. Must be a version of this agent; any version qualifies, so you can re-check an older one. Omit it (or pass an empty string) to score what a promotion into this environment would deploy: for
production, the version pinned to staging; for staging, the newest version saved on the main line. Returns 400 BAD_REQUEST when the ID is not a version of this agent, or when the default cannot be resolved (staging is unpinned, or the agent has no saved versions).Response
Returns202 with the new run. If the run could not be scheduled, the response is still 202 but the run’s status is ERROR with an error_message, so read the status rather than assuming PENDING.
Returns 400 BAD_REQUEST when the environment has no check config, the config is disabled, or the config is no longer runnable (for example, a scenario was deleted). Returns 409 CONFLICT while another run for the same environment is PENDING or RUNNING; cancel it with Cancel Check Run or wait for it to finish.
object
The new check run.
Show check run object
Show check run object
string
Unique identifier for the check run. Pass it as
{run_id} when polling.string
The agent the run belongs to.
string
The environment whose checks were run:
staging or production.string
The candidate version the run scores.
string | null
The candidate’s published version number.
null when the candidate has not been published yet, which is the normal case for a staging run.string | null
The candidate’s saved name, or
null if it has none.string
PENDING on a successful start, or ERROR if the run could not be scheduled. Later values are RUNNING, PASSED, FAILED, ERROR, and CANCELLED.array
Display names of the judges frozen into the run.
integer
Number of scenarios the run drives conversations from.
integer
Conversations generated per scenario.
boolean | null
null until the run completes. true when every required judge passed, false otherwise.array | null
null until the run completes. See Get Check Run for the verdict object.string | null
ID of the generated conversation set.
null until generation starts.string | null
ID of the scoring run.
null until scoring starts.string | null
Why the run ended in
ERROR, or null.string | null
ID of the user who started the run, or
null when started with an org-level key.string
ISO 8601 timestamp the run was created.
string | null
When scoring began.
null while PENDING.string | null
When the run reached a terminal status.
null while in flight.null | array
null on success, or a list of error objects if the request failed.{
"data": {
"id": "e8b994db-eeaa-4948-a4b8-3edbca49ca9c",
"agent_id": "9b97c1a6-3171-4139-b83d-b9119586080d",
"env_type": "production",
"agent_version_id": "b7a09422-c97c-49d8-b66f-8991b14e8253",
"semver": "1.4.0",
"version_name": "Shorter greeting",
"status": "PENDING",
"judge_names": ["Resolution quality", "No policy violations"],
"scenario_count": 2,
"simulations_count": 5,
"overall_passed": null,
"verdicts": null,
"simulation_set_id": null,
"eval_run_id": null,
"error_message": null,
"triggered_by": "c43222b9-b7ab-4823-950d-517ac22291ff",
"created_at": "2026-09-10T17:02:39.115Z",
"started_at": null,
"completed_at": null
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "No checks are configured for this environment"
}
]
}
{
"data": null,
"errors": [
{
"error": "CONFLICT",
"message": "A check run is already in progress"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?