Tests & Builds
Fetch test results, report pass/fail state back from your CI, and work with the builds that group them.
- Endpoint
- api.testingbot.com
- Version
- v1
- Format
- JSON
- Auth
- HTTP Basic
Changed August 2026: the browser field is now a stable identifier without the version (for example googlechrome rather than Chrome 150), so it is safe to match on. The human-readable label moved to the new browser_display_name field, and browser_long_version carries the full version string when known. Integrations that matched on the old combined label should match on browser plus browser_version instead.
/v1/tests
List your tests
Paginated list of every test session belonging to the authenticated account, newest first. Filter bybrowser_id, group, or build to narrow the result. Use since to fetch only tests updated after a UNIX timestamp (poll-friendly).
Arguments
-
offsetinteger - Skip this many tests from the start of the result set.
-
countinteger - Number of tests to return .
-
sinceinteger - UNIX timestamp; return only tests updated at or after this time.
-
browser_idinteger - Filter to tests that ran on this browser_id (from /v1/browsers).
-
groupstring - Filter to tests tagged with this group name.
-
buildstring -
Filter to tests in this build (matches
capabilities.build). -
skip_fieldsstring - Comma-separated fields to omit (logs, thumbs).
Response fields
-
dataarray of test case objects - Test sessions for this page.
-
metameta object - —
-
realtimeobject -
ActionCable channel details for live updates. Only present on the
since-polling form of this endpoint.
$ curl "https://api.testingbot.com/v1/tests?offset=0&count=10" \
-u key:secret
var client = new TestingBotClient(key, secret);
var tests = await client.Tests.ListAsync();
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_tests(0, 10)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.get_tests(offset=0, limit=10)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getJobs(0, 10);
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotTestCollection tests = restApi.getTests(0, 10);
const TestingBot = require('testingbot-api');
const api = new TestingBot({
api_key: "your-tb-key",
api_secret: "your-tb-secret"
});
const tests = await api.getTests({ offset: 0, limit: 10 });
{
"data": [
{
"created_at": "2011-07-30T23:21:23Z",
"completed_at": "2011-07-30T23:22:44Z",
"id": 3,
"name": "MyTest::testTitle",
"session_id": "f7903f9e93e74fe1b0e924bf9d2ce9fc",
"status_message": "Failed asserting that 1 equals 0.",
"status_id": 0,
"success": false,
"browser": "iexplore",
"browser_version": "8",
"browser_long_version": "8.0.7601",
"browser_display_name": "IE8",
"os": "WINDOWS",
"duration": 13,
"build": "buildid",
"video": "https://s3.amazonaws.com/rectestingbot/sample.mp4",
"groups": ["testingbot.com"]
}
],
"meta": { "offset": 0, "count": 10, "total": 789 }
}
/v1/tests/:id
Get a specific test
Returns the full detail record for a single test session: status, environment (browser/OS or device/platform), assets (video, logs, screenshots), groups, build, and duration. Accepts either the numeric test ID or the WebDriver session_id.Arguments
-
idstring required - Numeric test ID or WebDriver session_id (UUID).
-
skip_fieldsstring - Comma-separated fields to omit from the response (logs, thumbs, visual_run, groups).
Response fields
-
idinteger - Unique numeric test ID.
-
session_idstring - Selenium / WebDriver session ID (UUID).
-
namestring -
Human-readable test name set via capabilities or
update_test. -
statestring - Lifecycle state (RUNNING, COMPLETE, TIMEOUT, …).
-
successboolean - Whether the test passed.
-
status_idinteger - Numeric status code (0=fail, 1=pass, 2=unknown).
-
unknownboolean -
Convenience flag, true when
status_idis 2 (the test finished without reporting a pass/fail). -
status_messagestring -
Failure reason or arbitrary status set via
test[status_message]. -
created_attimestamp - When the test session started.
-
completed_attimestamp - When the session ended; null while running.
-
durationinteger - Total run time in seconds.
-
browserstring - Browser identifier, without the version (e.g. "googlechrome", "iexplore", "firefox", "safari"). Stable across versions, so it is the field to match on.
-
browser_versionstring - Browser version as a string, not a number: it may carry minor/patch components (e.g. "150", "11.4"), and is "0" for environments with no meaningful version.
-
browser_long_versionstring - Full version string when known (e.g. "121.0.6167.184"); null otherwise.
-
browser_display_namestring - Human-readable label for UIs (e.g. "Chrome 150", "IE11", "Safari 11"), with the device and OS appended on mobile. Presentation only: the format is not stable, so build UI strings from it but never match on it.
-
osstring - OS (e.g. "WINDOWS", "MAC").
-
device_namestring - Mobile device name when the session ran on a physical device; null otherwise.
-
platform_namestring - Mobile OS name; null on desktop.
-
buildstring - Build identifier (free-form string set via capabilities).
-
groupsarray of string - Tag/group names attached to the test.
-
videostring - Signed S3 URL to the recorded video, or false if video was disabled.
-
thumbsarray of string - Signed S3 URLs to screenshot thumbnails.
-
logsobject - Map of log names → signed S3 URLs (selenium, browser, …).
-
assets_availableboolean - Whether assets (video, logs, screenshots) have finished processing.
-
extrastring -
Arbitrary metadata string set via
test[extra]. -
typestring - Driver type (WEBDRIVER, APPIUM).
-
stepsstring -
Rendered HTML of the recorded step list. Omit with
skip_fields=steps. -
runninginteger - Completion percentage. Only present while a Codeless test is still running.
$ curl "https://api.testingbot.com/v1/tests/:id" -u key:secret
var client = new TestingBotClient(key, secret);
var test = await client.Tests.GetAsync(testId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_test(test_id)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.get_test(test_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getJob($test_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotTest test = restApi.getTest(test_id);
const TestingBot = require('testingbot-api');
const api = new TestingBot({
api_key: "your-tb-key",
api_secret: "your-tb-secret"
});
const test = await api.getTestDetails(testId);
{
"id": 3,
"name": "MyTest::testTitle",
"session_id": "f7903f9e93e74fe1b0e924bf9d2ce9fc",
"state": "COMPLETE",
"success": false,
"status_id": 0,
"unknown": false,
"status_message": "Failed asserting that 1 equals 0.",
"created_at": "2011-07-30T23:21:23Z",
"completed_at": "2011-07-30T23:22:23Z",
"duration": 60,
"browser": "iexplore",
"browser_version": "8",
"browser_long_version": "8.0.7601",
"browser_display_name": "IE8",
"os": "WINDOWS",
"device_name": null,
"platform_name": null,
"build": null,
"groups": ["testingbot.com"],
"video": "https://s3.amazonaws.com/rectestingbot/sample.mp4",
"thumbs": ["https://s3.amazonaws.com/euthumbtestingbot/3_f93782fji.jpg"],
"logs": { "selenium": "https://s3-eu-west-1.amazonaws.com/eulogtestingbot/session.txt" },
"assets_available": true,
"type": "WEBDRIVER"
}
/v1/tests/:id
Update a test
Updates a test's metadata after it's been recorded. Use this to mark a test as passed/failed from the test runner, attach groups/tags, set a build identifier, or add a status message. Accepts either a numeric test ID or a WebDriver session_id.Arguments
-
idstring required - Numeric test ID or WebDriver session_id (UUID).
-
test[name]string - Human-readable test name.
-
test[success]boolean - true=pass, false=fail.
-
test[status_message]string - Failure reason or arbitrary status text.
-
test[extra]string - Arbitrary metadata.
-
test[build]string - Build identifier to associate this test with.
-
test[public]boolean - When true, makes the test publicly viewable via share URL.
-
groupsstring - Comma-separated string or array of tag/group names to attach to the test.
-
buildstring -
Build identifier (alternative location to
test[build]).
Response fields
-
successboolean - Whether the operation succeeded.
-
errorsobject -
Validation errors keyed by field name. Only present when
successis false. -
errorstring -
Single human-readable reason, used by the older endpoints in place of
errors. Only present whensuccessis false.
$ curl "https://api.testingbot.com/v1/tests/:id" \
-X PUT \
-d "test[success]=1" \
-d "groups[]=regression" \
-u key:secret
var client = new TestingBotClient(key, secret);
await client.Tests.UpdateAsync(testId, new TestUpdate { Success = true, Groups = new[] { "regression" } });
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.update_test(test_id, { name: 'new_name', success: true })
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.update_test(test_id, status_message='..', passed=1, build='..', name='..')
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->updateJob($test_id, ['name' => 'mytest', 'success' => true]);
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.updateTest(testId, details);
const TestingBot = require('testingbot-api');
const api = new TestingBot({
api_key: "your-tb-key",
api_secret: "your-tb-secret"
});
await api.updateTest({ 'test[success]': '1', 'test[status_message]': 'failure reason' }, testId);
{
"success": true
}
/v1/tests/:id
Delete a test
Permanently deletes a test session and every associated asset (video, logs, screenshots). This action cannot be undone.Arguments
-
idstring required - Numeric test ID or WebDriver session_id of the test to delete.
$ curl "https://api.testingbot.com/v1/tests/:id" \
-X DELETE \
-u key:secret
var client = new TestingBotClient(key, secret);
await client.Tests.DeleteAsync(testId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.delete_test(test_id)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.delete_test(test_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->deleteJob($test_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.deleteTest(testId);
const TestingBot = require('testingbot-api');
const api = new TestingBot({
api_key: "your-tb-key",
api_secret: "your-tb-secret"
});
await api.deleteTest(testId);
{
"success": true
}
/v1/tests/:id/assets
List a test's assets
Returns presigned download URLs for everything the session produced: video, per-type log files, HAR network capture, performance metrics and screenshots. URLs expire (video/logs/HAR after 1 hour, screenshots after 7 days) -- fetch this again for fresh ones. Ideal for archiving artifacts from CI after a run.Arguments
-
idstring required - Numeric test ID or WebDriver session_id.
Response fields
-
session_idstring - WebDriver session id of the test the assets belong to.
-
videostring - Presigned video URL (valid 1 hour). Null when no video was recorded or assets were deleted.
-
logsobject - Presigned log-file URLs keyed by log type (selenium, appium, logcat, browser, ...), each valid 1 hour. Empty object when none remain.
-
harstring - Presigned HAR network-capture URL (valid 1 hour). Null unless network capture was enabled for the session.
-
performancestring - Presigned performance-metrics log URL (valid 1 hour). Null unless performance data was collected.
-
screenshotsarray of string - Presigned screenshot URLs in capture order, each valid 7 days.
$ curl "https://api.testingbot.com/v1/tests/:id/assets" -u key:secret
{
"session_id": "2b5a38f3c71e97a2265b52b9382db1c5",
"video": "https://eurectestingbot.../screencast.mp4?X-Amz-Expires=3600...",
"logs": {
"selenium": "https://eulogtestingbot.../selenium.log?X-Amz-Expires=3600..."
},
"har": null,
"performance": null,
"screenshots": [
"https://euthumbtestingbot.../2b5a38f3_1.jpg?X-Amz-Expires=604800..."
]
}
/v1/tests/:id/assets
Delete a test's assets
Permanently deletes the session's stored files -- video, log files, HAR capture and screenshots -- ahead of the normal retention window, e.g. for compliance. The test result itself (status, metadata, command history) is kept; use DELETE /v1/tests/:id to remove the whole test. Idempotent: deleting a test with no remaining assets succeeds.Arguments
-
idstring required - Numeric test ID or WebDriver session_id.
$ curl -X DELETE "https://api.testingbot.com/v1/tests/:id/assets" -u key:secret
{ "success": true }
/v1/tests/:id/ai_analysis
Get the AI failure analysis of a test
Returns the AI failure analysis of a test: a summary, the most likely root cause, a timeline, the supporting log evidence and suggested fixes (Markdown), plus a failure category, the likely owner and a confidence score. Reading never starts an analysis:status is none until one is requested with POST. While it runs, sections holds what has been written so far. Requires the account owner to have enabled AI Analysis in Account Settings; otherwise 403 with code ai_analysis_not_enabled.
Arguments
-
idstring required - Numeric test ID or WebDriver session_id.
Response fields
-
test_idinteger - Numeric ID of the test.
-
session_idstring - WebDriver session id of the test.
-
statusstring -
none(never requested),pending,running,completeorfailed. -
errorstring -
Why a
failedanalysis stopped, e.g.quota_exceeded, orunavailable:<reason>when the test has no usable logs. Null otherwise. -
categorystring - Failure category: timeout, element_not_found, assertion_failed, app_crash, navigation_error, network_error, auth_required, setup_error, flaky or unknown.
-
owner_classstring - Where the problem most likely sits: application, test_script, environment, flaky or unknown.
-
confidenceinteger - Confidence score, 0-100.
-
confidence_bandstring -
low,mediumorhigh. -
sectionsobject -
The analysis text. Partial while
running; empty fornone. -
staleboolean - True when the analysis was made by an older model or prompt; POST again to refresh it.
-
modelstring - Model that wrote the analysis.
-
completed_attimestamp - When the analysis finished.
-
test_urlstring - The test in the TestingBot dashboard, where the AI Analysis tab shows the same result.
$ curl "https://api.testingbot.com/v1/tests/:id/ai_analysis" -u key:secret
import requests
res = requests.get(
f'https://api.testingbot.com/v1/tests/{test_id}/ai_analysis',
auth=(key, secret))
analysis = res.json()
{
"test_id": 4711,
"session_id": "2b5a38f3c71e97a2265b52b9382db1c5",
"status": "complete",
"error": null,
"category": "element_not_found",
"owner_class": "application",
"confidence": 86,
"confidence_band": "high",
"sections": {
"summary": "The checkout test failed because the **Pay now** button never appeared.",
"root_cause": "`#pay-now` was not rendered after the cart loaded; the page showed an error banner instead.",
"timeline": "1. Opened /cart\n2. Clicked **Checkout**\n3. Waited 30s for `#pay-now`: not found",
"evidence": "`NoSuchElementException: no such element: #pay-now`",
"fixes": "1. Check why the payment form errors on this cart.\n2. Wait for the cart total before looking for the button."
},
"stale": false,
"model": "claude-haiku-4-5",
"completed_at": "2026-11-16T09:12:44Z",
"test_url": "https://testingbot.com/members/tests/4711"
}
/v1/tests/:id/ai_analysis
Analyze a test with AI
Starts an AI failure analysis of a finished test and returns its state; poll GET /v1/tests/{id}/ai_analysis untilstatus is complete or failed. A current analysis is returned as-is without running again (no extra cost) unless force is true. Passed tests can be analyzed too. Per-account daily and monthly limits apply; an analysis over the limit ends failed with error quota_exceeded. Requires the account owner to have enabled AI Analysis in Account Settings; otherwise 403 with code ai_analysis_not_enabled. Limited to 60 calls per 5 minutes per API key.
Arguments
-
idstring required - Numeric test ID or WebDriver session_id.
-
forceboolean - Run a fresh analysis even when a current one exists (counts towards the limits).
$ curl -X POST "https://api.testingbot.com/v1/tests/:id/ai_analysis" -u key:secret
import requests
res = requests.post(
f'https://api.testingbot.com/v1/tests/{test_id}/ai_analysis',
auth=(key, secret))
analysis = res.json() # poll GET .../ai_analysis until status is complete or failed
{
"test_id": 4711,
"session_id": "2b5a38f3c71e97a2265b52b9382db1c5",
"status": "pending",
"sections": {},
"test_url": "https://testingbot.com/members/tests/4711"
}
/v1/tests/:id/stop
Stop a running test
Terminates an in-flight test session. The test is marked complete; any assets gathered (video, logs, screenshots) become available for download. Returns 404 if the test has already finished.Arguments
-
idstring required - Numeric test ID or WebDriver session_id of the test to stop.
Response fields
-
successboolean - Whether the operation succeeded.
-
errorsobject -
Validation errors keyed by field name. Only present when
successis false. -
errorstring -
Single human-readable reason, used by the older endpoints in place of
errors. Only present whensuccessis false.
$ curl "https://api.testingbot.com/v1/tests/:id/stop" \
-X PUT \
-u key:secret
var client = new TestingBotClient(key, secret);
await client.Tests.StopAsync(testId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.stop_test(test_id)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.stop_test(test_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->stopJob($test_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.stopTest(testId);
const TestingBot = require('testingbot-api');
const api = new TestingBot({
api_key: "your-tb-key",
api_secret: "your-tb-secret"
});
await api.stopTest(testId);
{
"success": true
}
/v1/tests
Bulk delete tests
Deletes up to 25 tests -- and every associated asset (video, logs, screenshots) -- in one request. Each entry may be a numeric test ID or a WebDriver session_id. Tests that cannot be found (or belong to another account) are reported inmissing; the rest are gone for good, exactly like DELETE /v1/tests/:id. success is false whenever any id is missing, even though the ids that were found have been deleted, so check deleted and missing rather than success alone.
Arguments
-
idsarray required - Up to 25 numeric test IDs or WebDriver session_ids.
$ curl -X DELETE "https://api.testingbot.com/v1/tests?ids[]=123&ids[]=2b5a38f3c71e97a2265b52b9382db1c5" -u key:secret
{ "success": true, "deleted": ["123", "2b5a38f3c71e97a2265b52b9382db1c5"], "missing": [] }
/v1/tests
Create a test record (manual sessions)
Creates a TestCase record from outside the WebDriver/Appium flow. Mainly used by clients that want to log a manual or external test result against their TestingBot account. Most users will not need this — the normal flow is to start a Selenium/Appium session, and the record is created automatically.Arguments
-
test[name]string required - Test name.
-
test[test_environment_id]integer required -
Browser environment the result is attributed to (
browser_idfrom GET /v1/browsers). -
test[success]boolean - true=pass, false=fail.
-
test[status_message]string - Failure reason or status string.
-
test[extra]string - Arbitrary metadata.
-
test[build]string - Build identifier.
$ curl -X POST "https://api.testingbot.com/v1/tests" \
-u key:secret \
-d "test[name]=MyTest::testTitle" \
-d "test[test_environment_id]=1" \
-d "test[success]=true"
$client = new TestingBot\Client($key, $secret);
$client->tests()->create([
'name' => 'MyTest::testTitle',
'test_environment_id' => 1,
'success' => true,
]);
TestingbotREST restApi = new TestingbotREST(key, secret);
Map<String, Object> test = Map.of(
"name", "MyTest::testTitle",
"test_environment_id", 1,
"success", true);
boolean success = restApi.createTest(test);
/v1/tests/{id}
Update a test (POST alias)
Alias ofPUT /v1/tests/:id for clients that cannot send PUT requests (some older HTTP libraries). Same body schema and behavior — see PUT for the canonical form.
Arguments
-
idstring required - Numeric test ID or WebDriver session_id (UUID).
-
test[name]string - Human-readable test name.
-
test[success]boolean - true=pass, false=fail.
-
test[status_message]string - Failure reason or arbitrary status text.
-
test[extra]string - Arbitrary metadata.
-
test[build]string - Build identifier to associate this test with.
-
test[public]boolean - When true, makes the test publicly viewable via share URL.
-
groupsstring - Comma-separated string or array of tag/group names to attach to the test.
$ curl -X POST "https://api.testingbot.com/v1/tests/{id}" \
-u key:secret \
-d "test[success]=1" \
-d "test[status_message]=passed"
/v1/builds
List your builds
Returns a paginated list of test builds. A build is an aggregation of test cases that share the samecapabilities.build identifier, useful for grouping CI runs.
Arguments
-
offsetinteger - Skip this many builds from the start of the result set.
-
countinteger - Number of builds to return .
-
tagstring - Only return builds carrying this tag (set tags with PUT /v1/builds/:id).
Response fields
-
dataarray of build objects - Builds for this page.
-
metameta object - —
$ curl "https://api.testingbot.com/v1/builds?offset=0&count=10" \
-u key:secret
var client = new TestingBotClient(key, secret);
var builds = await client.Builds.ListAsync();
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_builds(0, 10)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.build.get_builds(offset=0, limit=10)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getBuilds(0, 10);
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotBuildCollection builds = restApi.getBuilds(0, 10);
const TestingBot = require('testingbot-api');
const api = new TestingBot({
api_key: "your-tb-key",
api_secret: "your-tb-secret"
});
const builds = await api.getBuilds(0, 10);
{
"data": [
{
"id": 4331,
"build_identifier": "first-build",
"created_at": "2016-08-01T11:09:02.000Z",
"updated_at": "2016-08-01T11:09:02.000Z"
}
],
"meta": { "offset": 0, "count": 10, "total": 3 }
}
/v1/builds/:id
Get tests for a build
Returns all test cases that belong to a single build, with pagination. The build can be referenced by either its numeric internal ID or the string identifier you set viacapabilities.build.
Arguments
-
idstring required - Numeric build ID or string build identifier.
-
offsetinteger - Skip this many tests in the build.
-
countinteger - Number of tests to return .
-
skip_fieldsstring - Comma-separated fields to omit from each test (logs, thumbs).
-
statusstring -
Only return tests with this result: failed, passed or unknown (no result set).
status=failedlists the tests a CI job should re-run.
Response fields
-
dataarray of test case objects - Test sessions for this page.
-
metameta object - —
-
realtimeobject -
ActionCable channel details for live updates. Only present on the
since-polling form of this endpoint.
$ curl "https://api.testingbot.com/v1/builds/:id" \
-u key:secret
var client = new TestingBotClient(key, secret);
var tests = await client.Builds.GetTestsAsync(buildId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_build(build_identifier)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.build.get_tests_for_build(build_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getBuild($build_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotTestBuildCollection tests = restApi.getTestsForBuild(buildId);
const TestingBot = require('testingbot-api');
const api = new TestingBot({
api_key: "your-tb-key",
api_secret: "your-tb-secret"
});
const tests = await api.getTestsForBuild(buildId);
{
"data": [
{
"id": 3,
"name": "MyTest::testTitle",
"session_id": "f7903f9e93e74fe1b0e924bf9d2ce9fc",
"state": "COMPLETE",
"success": false,
"status_id": 0,
"created_at": "2011-07-30T23:21:23Z",
"completed_at": "2011-07-30T23:22:44Z",
"duration": 13,
"browser": "iexplore",
"browser_version": "8",
"browser_long_version": "8.0.7601",
"browser_display_name": "IE8",
"os": "WINDOWS",
"build": "buildid",
"video": "https://s3.amazonaws.com/rectestingbot/sample.mp4"
}
],
"meta": { "offset": 0, "count": 10, "total": 1 }
}
/v1/builds/:id
Delete a build
Permanently deletes a build and every test, asset (video, logs, screenshots) attached to it. This action cannot be undone.Arguments
-
idstring required - Numeric build ID or string build identifier to delete.
$ curl "https://api.testingbot.com/v1/builds/:id" \
-X DELETE \
-u key:secret
var client = new TestingBotClient(key, secret);
await client.Builds.DeleteAsync(buildId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.delete_build(build_identifier)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.build.delete_build(build_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->deleteBuild($build_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.deleteBuild(buildId);
const TestingBot = require('testingbot-api');
const api = new TestingBot({
api_key: "your-tb-key",
api_secret: "your-tb-secret"
});
await api.deleteBuild(buildId);
{
"success": true
}
/v1/builds/:id
Update a build (rename, tags)
Renames a build and/or replaces its tag set. Tags are short labels (letters, digits, dot, dash, underscore, colon, space; max 50 chars each, 10 per build) you can filter the builds list by (GET /v1/builds?tag=...) -- handy for marking CI runs as smoke, nightly, release-x and so on. Passing an empty tags array (JSON body) clears them.
Arguments
-
idstring required - Numeric build ID or string build identifier.
-
namestring - New build identifier (capabilities.build value).
-
tagsarray - Replacement tag set; empty array clears all tags.
Response fields
-
successboolean - Whether the build was updated.
-
buildobject - The updated build: id, build_identifier and tags.
$ curl -X PUT "https://api.testingbot.com/v1/builds/:id" \
-d "name=nightly-2026-08-11" -d "tags[]=smoke" -d "tags[]=release-1.4" \
-u key:secret
{
"success": true,
"build": { "id": 4711, "build_identifier": "nightly-2026-08-11", "tags": ["smoke", "release-1.4"] }
}
/v1/builds
Bulk delete builds
Deletes up to 25 builds in one request. Each entry may be a numeric build ID or a string build identifier. Builds that cannot be found (or belong to another account) are reported inmissing; the rest are deleted like DELETE /v1/builds/:id (tests keep their results, only the build grouping is removed). success is false whenever any id is missing, even though the builds that were found have been deleted, so check deleted and missing rather than success alone.
Arguments
-
idsarray required - Up to 25 numeric build IDs or string build identifiers.
$ curl -X DELETE "https://api.testingbot.com/v1/builds?ids[]=4711&ids[]=nightly-2026-08-10" -u key:secret
{ "success": true, "deleted": ["4711", "nightly-2026-08-10"], "missing": [] }
/v1/builds/{id}/ci
Link a build to a commit for CI status checks
Associates a CI build with the commit/PR it ran for on a code host and posts an in-progress status check. Currently supportsgithub (requires the TestingBot GitHub App installed on the repository owner). Call this at the start of a workflow run.
Arguments
-
idstring required - Build identifier (capabilities.build) for this run.
-
repostring required - Repository in owner/name form.
-
commit_shastring required - Head commit SHA the build ran for. For pull_request events use github.event.pull_request.head.sha (not the merge commit) so the check lands on the SHA branch protection evaluates.
-
providerstring - Code host provider. Currently only "github".
-
branchstring - Git branch name.
-
pull_request_numberinteger - Pull request number, if any.
$ curl -X POST "https://api.testingbot.com/v1/builds/{id}/ci" \
-u key:secret \
-d "repo=my-org/my-repo" \
-d "commit_sha=9fceb02d0ae598e95dc970b74767f19372d61af8" \
-d "branch=main"
/v1/builds/{id}/ci
Report a CI status-check build as finished
Signals that the CI run for this build has finished, so the status check is updated with the aggregate pass/fail result. Call this after your tests complete.Arguments
-
idstring required - Build identifier (capabilities.build) for this run.
-
providerstring - Code host provider. Currently only "github".
Response fields
-
successboolean - Whether the operation succeeded.
-
errorsobject -
Validation errors keyed by field name. Only present when
successis false. -
errorstring -
Single human-readable reason, used by the older endpoints in place of
errors. Only present whensuccessis false.
$ curl -X PUT "https://api.testingbot.com/v1/builds/{id}/ci" \
-u key:secret
/v1/visual/tests/{id}/run
Run a visual test from CI
Runs a hosted visual test in all of its browsers and returns a check id to poll. Passurl to screenshot a preview deployment instead of the test's URL for this run only: it is compared with the test's normal baselines and never becomes one. The preview URL must be on the same domain as the test's URL or match one of the preview hosts set on the test, and must resolve to a public address (use a tunnel for private hosts). Pass repo and commit to also report the result as a GitHub check on that commit (requires the TestingBot GitHub App on the repository owner). Limited to 60 calls per 5 minutes per API key.
Arguments
-
idinteger required - ID of the visual test.
-
urlstring - Preview URL to screenshot instead of the test's URL, for this run only.
-
repostring - GitHub repository in owner/name form, to report the result as a check.
-
commitstring - Head commit SHA the check is posted on. Required with repo.
-
printeger - Pull request number, for the summary comment on the pull request.
-
branchstring - Git branch name.
$ curl -X POST "https://api.testingbot.com/v1/visual/tests/{id}/run" \
-u key:secret \
-d "url=https://pr-42.preview.example.com/" \
-d "repo=my-org/my-repo" \
-d "commit=9fceb02d0ae598e95dc970b74767f19372d61af8" \
-d "pr=42"
{
"success": true,
"check": "4f1c2b9a0d3e5f67",
"test_id": 1234,
"url": "https://pr-42.preview.example.com/",
"preview": true,
"browsers": 3,
"github": true,
"status_url": "https://api.testingbot.com/v1/visual/checks/4f1c2b9a0d3e5f67"
}
/v1/visual/checks/{check}
Get a visual check
Returns the state of a check started with POST /v1/visual/tests/{id}/run: per browser whether it has been compared, whether it passed, the mismatch percentage and a link to the run page.state turns done when every browser has finished; passed is true only when every browser compared and passed. Checks can be read for 7 days.
Arguments
-
checkstring required - Check id returned when the check was started.
Response fields
-
checkstring - Check id.
-
test_idinteger - The visual test.
-
urlstring - The preview URL; null when the check ran the test's own URL, or once the check is older than 7 days.
-
previewboolean - Whether a preview URL replaced the test's URL.
-
statestring -
runninguntil every browser finished, thendone. -
passedboolean -
true when every browser compared and passed, false otherwise. null while
running. -
test_urlstring - The visual test in the TestingBot dashboard.
-
browsersarray of visual check browser objects - One entry per browser of the test.
$ curl "https://api.testingbot.com/v1/visual/checks/{check}" \
-u key:secret
{
"check": "4f1c2b9a0d3e5f67",
"test_id": 1234,
"url": "https://pr-42.preview.example.com/",
"preview": true,
"state": "done",
"passed": false,
"test_url": "https://testingbot.com/members/uitest/1234",
"browsers": [
{
"configuration_id": 801,
"browser": "Chrome 149, Windows 11",
"state": "done",
"passed": false,
"mismatch": 2.41,
"threshold": 1.0,
"run_url": "https://testingbot.com/members/visual/5521/runs/99812"
}
]
}
/v1/accessibility/scans
Save an accessibility scan
Saves an axe-core result for a page to your account, as the TestingBot browser extension does from its DevTools panel. TestingBot does not load the page: the scan already ran in your browser, so local and private URLs are accepted. The score and counts are computed by TestingBot fromresults, with the same rules as scheduled accessibility scans. Free and trial accounts can save 10 scans per calendar month (UTC); paid plans have no limit. The request body is limited to 5 MB. An optional screenshot is stored with the scan; if storing it fails the scan is still saved and screenshot is false.
Arguments
-
urlstring required - The scanned page (http, https or file URL), at most 2048 characters.
-
resultsjson required -
The axe-core result object (with
violations,incompleteandpasses). -
standardstring - Standard the scan ran against.
-
titlestring - Page title.
-
scopestring -
page, orselectionwhen only one element was scanned. -
browserstring - Browser the scan ran in.
-
extension_versionstring - Version of the extension that sent it.
-
viewport_widthinteger - Viewport width in CSS pixels.
-
viewport_heightinteger - Viewport height in CSS pixels.
-
keyboardjson - Result of the extension's keyboard check (tab order, traps).
-
contextjson - Scan context: selector of a scanned selection, axe options, frames scanned, and the scroll offset and device pixel ratio of a screenshot.
-
screenshotstring -
The visible part of the page as a base64 JPEG or PNG (a
data:URL is accepted too), at most 2 MB decoded.
$ curl -X POST "https://api.testingbot.com/v1/accessibility/scans" \
-u key:secret \
-H "Content-Type: application/json" \
-d '{"url": "https://www.example.com/", "standard": "wcag21aa", "results": '"$(cat axe-results.json)"'}'
{
"id": 1842,
"url": "https://www.example.com/",
"title": "Example Domain",
"standard": "wcag21aa",
"score": 88,
"passed": false,
"wcag_issues_count": 3,
"needs_review_count": 2,
"recommendations_count": 1,
"severity": { "critical": 1, "serious": 2, "moderate": 0, "minor": 0 },
"screenshot": false,
"report_url": "https://testingbot.com/members/accessibility/extension-scans/1842",
"created_at": "2026-11-16T10:12:44.000Z",
"saves_left": 7
}
/v1/accessibility/scans/quota
Get your saved-scan quota
How many accessibility scans the account can still save this calendar month (UTC). Free and trial accounts can save 10 per month; on paid plans every field butsaved_this_month is null.
Response fields
-
monthly_limitinteger - Scans the account can save per calendar month (UTC); null when unlimited.
-
saved_this_monthinteger - Scans saved this calendar month.
-
saves_leftinteger - Saves left this month; null when unlimited.
-
upgrade_urlstring - Where to raise the limit; null when unlimited.
$ curl "https://api.testingbot.com/v1/accessibility/scans/quota" \
-u key:secret
{
"monthly_limit": 10,
"saved_this_month": 3,
"saves_left": 7,
"upgrade_url": "https://testingbot.com/pricing"
}