---
title: Tests & Builds API | TestingBot API Documentation
description: Retrieve, update, stop and delete your Selenium, Cypress and Playwright
  test results, and group them into builds.
source_url:
  html: https://testingbot.com/support/api/tests
  md: https://testingbot.com/support/api/tests.md
---

# 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](https://testingbot.com/support/api#authentication)

**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.

GET `/v1/tests`

## List your tests
 Paginated list of every test session belonging to the authenticated account, newest first. Filter by `browser_id`, `group`, or `build` to narrow the result. Use `since` to fetch only tests updated after a UNIX timestamp (poll-friendly). 
### Arguments

- **`offset` integer:** Skip this many tests from the start of the result set.
- **`count` integer max=`500`:** Number of tests to return .
- **`since` integer:** UNIX timestamp; return only tests updated at or after this time.
- **`browser_id` integer:** Filter to tests that ran on this browser\_id (from /v1/browsers).
- **`group` string:** Filter to tests tagged with this group name.
- **`build` string:** Filter to tests in this build (matches `capabilities.build`).
- **`skip_fields` string:** Comma-separated fields to omit (logs, thumbs).

### Response fields

- **`data` array of test case objects:** Test sessions for this page.
- **`meta` meta object:** —
- **`realtime` object:** ActionCable channel details for live updates. Only present on the `since`-polling form of this endpoint.

GET `/v1/tests`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/tests?offset=0&count=10" \
-u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
var tests = await client.Tests.ListAsync();
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_tests(0, 10)
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.get_tests(offset=0, limit=10)
```

```php
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getJobs(0, 10);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotTestCollection tests = restApi.getTests(0, 10);
```

```javascript
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 });
```

Response

```json
{
  "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 }
}
```

GET `/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

- **`id` string required:** Numeric test ID or WebDriver session\_id (UUID).
- **`skip_fields` string:** Comma-separated fields to omit from the response (logs, thumbs, visual\_run, groups).

### Response fields

- **`id` integer:** Unique numeric test ID.
- **`session_id` string:** Selenium / WebDriver session ID (UUID).
- **`name` string:** Human-readable test name set via capabilities or `update_test`.
- **`state` string:** Lifecycle state (RUNNING, COMPLETE, TIMEOUT, …).
- **`success` boolean:** Whether the test passed.
- **`status_id` integer:** Numeric status code (0=fail, 1=pass, 2=unknown).
- **`unknown` boolean:** Convenience flag, true when `status_id` is 2 (the test finished without reporting a pass/fail).
- **`status_message` string:** Failure reason or arbitrary status set via `test[status_message]`.
- **`created_at` timestamp:** When the test session started.
- **`completed_at` timestamp:** When the session ended; null while running.
- **`duration` integer:** Total run time in seconds.
- **`browser` string:** Browser identifier, without the version (e.g. "googlechrome", "iexplore", "firefox", "safari"). Stable across versions, so it is the field to match on.
- **`browser_version` string:** 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_version` string:** Full version string when known (e.g. "121.0.6167.184"); null otherwise.
- **`browser_display_name` string:** 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.
- **`os` string:** OS (e.g. "WINDOWS", "MAC").
- **`device_name` string:** Mobile device name when the session ran on a physical device; null otherwise.
- **`platform_name` string:** Mobile OS name; null on desktop.
- **`build` string:** Build identifier (free-form string set via capabilities).
- **`groups` array of string:** Tag/group names attached to the test.
- **`video` string:** Signed S3 URL to the recorded video, or false if video was disabled.
- **`thumbs` array of string:** Signed S3 URLs to screenshot thumbnails.
- **`logs` object:** Map of log names → signed S3 URLs (selenium, browser, …).
- **`assets_available` boolean:** Whether assets (video, logs, screenshots) have finished processing.
- **`extra` string:** Arbitrary metadata string set via `test[extra]`.
- **`type` string:** Driver type (WEBDRIVER, APPIUM).
- **`steps` string:** Rendered HTML of the recorded step list. Omit with `skip_fields=steps`.
- **`running` integer:** Completion percentage. Only present while a Codeless test is still running.

GET `/v1/tests/:id`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/tests/:id" -u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
var test = await client.Tests.GetAsync(testId);
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_test(test_id)
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.get_test(test_id)
```

```php
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getJob($test_id);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotTest test = restApi.getTest(test_id);
```

```javascript
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);
```

Response

```json
{
  "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"
}
```

PUT `/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

- **`id` string 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.
- **`groups` string:** Comma-separated string or array of tag/group names to attach to the test.
- **`build` string:** Build identifier (alternative location to `test[build]`).

### Response fields

- **`success` boolean:** Whether the operation succeeded.
- **`errors` object:** Validation errors keyed by field name. Only present when `success` is false.
- **`error` string:** Single human-readable reason, used by the older endpoints in place of `errors`. Only present when `success` is false.

PUT `/v1/tests/:id`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/tests/:id" \
-X PUT \
-d "test[success]=1" \
-d "groups[]=regression" \
-u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
await client.Tests.UpdateAsync(testId, new TestUpdate { Success = true, Groups = new[] { "regression" } });
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.update_test(test_id, { name: 'new_name', success: true })
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.update_test(test_id, status_message='..', passed=1, build='..', name='..')
```

```php
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->updateJob($test_id, ['name' => 'mytest', 'success' => true]);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.updateTest(testId, details);
```

```javascript
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);
```

Response

```json
{
  "success": true
}
```

DELETE `/v1/tests/:id`

## Delete a test
 Permanently deletes a test session and every associated asset (video, logs, screenshots). This action cannot be undone. 
### Arguments

- **`id` string required:** Numeric test ID or WebDriver session\_id of the test to delete.

DELETE `/v1/tests/:id`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/tests/:id" \
-X DELETE \
-u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
await client.Tests.DeleteAsync(testId);
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.delete_test(test_id)
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.delete_test(test_id)
```

```php
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->deleteJob($test_id);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.deleteTest(testId);
```

```javascript
const TestingBot = require('testingbot-api');

const api = new TestingBot({
  api_key: "your-tb-key",
  api_secret: "your-tb-secret"
});

await api.deleteTest(testId);
```

Response

```json
{
  "success": true
}
```

GET `/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

- **`id` string required:** Numeric test ID or WebDriver session\_id.

### Response fields

- **`session_id` string:** WebDriver session id of the test the assets belong to.
- **`video` string:** Presigned video URL (valid 1 hour). Null when no video was recorded or assets were deleted.
- **`logs` object:** Presigned log-file URLs keyed by log type (selenium, appium, logcat, browser, ...), each valid 1 hour. Empty object when none remain.
- **`har` string:** Presigned HAR network-capture URL (valid 1 hour). Null unless network capture was enabled for the session.
- **`performance` string:** Presigned performance-metrics log URL (valid 1 hour). Null unless performance data was collected.
- **`screenshots` array of string:** Presigned screenshot URLs in capture order, each valid 7 days.

GET `/v1/tests/:id/assets`
[cURL](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/tests/:id/assets" -u key:secret
```

Response

```json
{
  "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..."
  ]
}
```

DELETE `/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

- **`id` string required:** Numeric test ID or WebDriver session\_id.

DELETE `/v1/tests/:id/assets`
[cURL](https://testingbot.com#)
Request

```bash
$ curl -X DELETE "https://api.testingbot.com/v1/tests/:id/assets" -u key:secret
```

Response

```json
{ "success": true }
```

GET `/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

- **`id` string required:** Numeric test ID or WebDriver session\_id.

### Response fields

- **`test_id` integer:** Numeric ID of the test.
- **`session_id` string:** WebDriver session id of the test.
- **`status` string:** `none` (never requested), `pending`, `running`, `complete` or `failed`.
- **`error` string:** Why a `failed` analysis stopped, e.g. `quota_exceeded`, or `unavailable:<reason>` when the test has no usable logs. Null otherwise.
- **`category` string:** Failure category: timeout, element\_not\_found, assertion\_failed, app\_crash, navigation\_error, network\_error, auth\_required, setup\_error, flaky or unknown.
- **`owner_class` string:** Where the problem most likely sits: application, test\_script, environment, flaky or unknown.
- **`confidence` integer:** Confidence score, 0-100.
- **`confidence_band` string:** `low`, `medium` or `high`.
- **`sections` object:** The analysis text. Partial while `running`; empty for `none`.
- **`stale` boolean:** True when the analysis was made by an older model or prompt; POST again to refresh it.
- **`model` string:** Model that wrote the analysis.
- **`completed_at` timestamp:** When the analysis finished.
- **`test_url` string:** The test in the TestingBot dashboard, where the AI Analysis tab shows the same result.

GET `/v1/tests/:id/ai_analysis`
[cURL](https://testingbot.com#) [Python](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/tests/:id/ai_analysis" -u key:secret
```

```python
import requests
res = requests.get(
  f'https://api.testingbot.com/v1/tests/{test_id}/ai_analysis',
  auth=(key, secret))
analysis = res.json()
```

Response

```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"
}
```

POST `/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 until `status` 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

- **`id` string required:** Numeric test ID or WebDriver session\_id.
- **`force` boolean:** Run a fresh analysis even when a current one exists (counts towards the limits).

POST `/v1/tests/:id/ai_analysis`
[cURL](https://testingbot.com#) [Python](https://testingbot.com#)
Request

```bash
$ curl -X POST "https://api.testingbot.com/v1/tests/:id/ai_analysis" -u key:secret
```

```python
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
```

Response

```json
{
  "test_id": 4711,
  "session_id": "2b5a38f3c71e97a2265b52b9382db1c5",
  "status": "pending",
  "sections": {},
  "test_url": "https://testingbot.com/members/tests/4711"
}
```

PUT `/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

- **`id` string required:** Numeric test ID or WebDriver session\_id of the test to stop.

### Response fields

- **`success` boolean:** Whether the operation succeeded.
- **`errors` object:** Validation errors keyed by field name. Only present when `success` is false.
- **`error` string:** Single human-readable reason, used by the older endpoints in place of `errors`. Only present when `success` is false.

PUT `/v1/tests/:id/stop`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/tests/:id/stop" \
-X PUT \
-u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
await client.Tests.StopAsync(testId);
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.stop_test(test_id)
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.stop_test(test_id)
```

```php
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->stopJob($test_id);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.stopTest(testId);
```

```javascript
const TestingBot = require('testingbot-api');

const api = new TestingBot({
  api_key: "your-tb-key",
  api_secret: "your-tb-secret"
});

await api.stopTest(testId);
```

Response

```json
{
  "success": true
}
```

DELETE `/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 in `missing`; 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

- **`ids` array required:** Up to 25 numeric test IDs or WebDriver session\_ids.

DELETE `/v1/tests`
[cURL](https://testingbot.com#)
Request

```bash
$ curl -X DELETE "https://api.testingbot.com/v1/tests?ids[]=123&ids[]=2b5a38f3c71e97a2265b52b9382db1c5" -u key:secret
```

Response

```json
{ "success": true, "deleted": ["123", "2b5a38f3c71e97a2265b52b9382db1c5"], "missing": [] }
```

POST `/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_id` from 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.

POST `/v1/tests`
[cURL](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#)
Request

```bash
$ 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"
```

```php
$client = new TestingBot\Client($key, $secret);
$client->tests()->create([
    'name' => 'MyTest::testTitle',
    'test_environment_id' => 1,
    'success' => true,
]);
```

```java
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);
```

POST `/v1/tests/{id}`

## Update a test (POST alias)
 Alias of `PUT /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

- **`id` string 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.
- **`groups` string:** Comma-separated string or array of tag/group names to attach to the test.

POST `/v1/tests/{id}`
[cURL](https://testingbot.com#)
Request

```bash
$ curl -X POST "https://api.testingbot.com/v1/tests/{id}" \
-u key:secret \
-d "test[success]=1" \
-d "test[status_message]=passed"
```

GET `/v1/builds`

## List your builds
 Returns a paginated list of test builds. A build is an aggregation of test cases that share the same `capabilities.build` identifier, useful for grouping CI runs. 
### Arguments

- **`offset` integer:** Skip this many builds from the start of the result set.
- **`count` integer max=`500`:** Number of builds to return .
- **`tag` string:** Only return builds carrying this tag (set tags with PUT /v1/builds/:id).

### Response fields

- **`data` array of build objects:** Builds for this page.
- **`meta` meta object:** —

GET `/v1/builds`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/builds?offset=0&count=10" \
-u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
var builds = await client.Builds.ListAsync();
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_builds(0, 10)
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.build.get_builds(offset=0, limit=10)
```

```php
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getBuilds(0, 10);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotBuildCollection builds = restApi.getBuilds(0, 10);
```

```javascript
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);
```

Response

```json
{
  "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 }
}
```

GET `/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 via `capabilities.build`. 
### Arguments

- **`id` string required:** Numeric build ID or string build identifier.
- **`offset` integer:** Skip this many tests in the build.
- **`count` integer max=`500`:** Number of tests to return .
- **`skip_fields` string:** Comma-separated fields to omit from each test (logs, thumbs).
- **`status` string:** Only return tests with this result: failed, passed or unknown (no result set). `status=failed` lists the tests a CI job should re-run.

### Response fields

- **`data` array of test case objects:** Test sessions for this page.
- **`meta` meta object:** —
- **`realtime` object:** ActionCable channel details for live updates. Only present on the `since`-polling form of this endpoint.

GET `/v1/builds/:id`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/builds/:id" \
-u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
var tests = await client.Builds.GetTestsAsync(buildId);
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_build(build_identifier)
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.build.get_tests_for_build(build_id)
```

```php
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getBuild($build_id);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotTestBuildCollection tests = restApi.getTestsForBuild(buildId);
```

```javascript
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);
```

Response

```json
{
  "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 }
}
```

DELETE `/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

- **`id` string required:** Numeric build ID or string build identifier to delete.

DELETE `/v1/builds/:id`
[cURL](https://testingbot.com#) [.NET](https://testingbot.com#) [Ruby](https://testingbot.com#) [Python](https://testingbot.com#) [PHP](https://testingbot.com#) [Java](https://testingbot.com#) [NodeJS](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/builds/:id" \
-X DELETE \
-u key:secret
```

```csharp
var client = new TestingBotClient(key, secret);
await client.Builds.DeleteAsync(buildId);
```

```ruby
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.delete_build(build_identifier)
```

```python
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.build.delete_build(build_id)
```

```php
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->deleteBuild($build_id);
```

```java
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.deleteBuild(buildId);
```

```javascript
const TestingBot = require('testingbot-api');

const api = new TestingBot({
  api_key: "your-tb-key",
  api_secret: "your-tb-secret"
});

await api.deleteBuild(buildId);
```

Response

```json
{
  "success": true
}
```

PUT `/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

- **`id` string required:** Numeric build ID or string build identifier.
- **`name` string:** New build identifier (capabilities.build value).
- **`tags` array:** Replacement tag set; empty array clears all tags.

### Response fields

- **`success` boolean:** Whether the build was updated.
- **`build` object:** The updated build: id, build\_identifier and tags.

PUT `/v1/builds/:id`
[cURL](https://testingbot.com#)
Request

```bash
$ 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
```

Response

```json
{
  "success": true,
  "build": { "id": 4711, "build_identifier": "nightly-2026-08-11", "tags": ["smoke", "release-1.4"] }
}
```

DELETE `/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 in `missing`; 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

- **`ids` array required:** Up to 25 numeric build IDs or string build identifiers.

DELETE `/v1/builds`
[cURL](https://testingbot.com#)
Request

```bash
$ curl -X DELETE "https://api.testingbot.com/v1/builds?ids[]=4711&ids[]=nightly-2026-08-10" -u key:secret
```

Response

```json
{ "success": true, "deleted": ["4711", "nightly-2026-08-10"], "missing": [] }
```

POST `/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 supports `github` (requires the TestingBot GitHub App installed on the repository owner). Call this at the start of a workflow run. 
### Arguments

- **`id` string required:** Build identifier (capabilities.build) for this run.
- **`repo` string required:** Repository in owner/name form.
- **`commit_sha` string 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.
- **`provider` string:** Code host provider. Currently only "github".
- **`branch` string:** Git branch name.
- **`pull_request_number` integer:** Pull request number, if any.

POST `/v1/builds/{id}/ci`
[cURL](https://testingbot.com#)
Request

```bash
$ 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"
```

PUT `/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

- **`id` string required:** Build identifier (capabilities.build) for this run.
- **`provider` string:** Code host provider. Currently only "github".

### Response fields

- **`success` boolean:** Whether the operation succeeded.
- **`errors` object:** Validation errors keyed by field name. Only present when `success` is false.
- **`error` string:** Single human-readable reason, used by the older endpoints in place of `errors`. Only present when `success` is false.

PUT `/v1/builds/{id}/ci`
[cURL](https://testingbot.com#)
Request

```bash
$ curl -X PUT "https://api.testingbot.com/v1/builds/{id}/ci" \
-u key:secret
```

POST `/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. Pass `url` 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

- **`id` integer required:** ID of the visual test.
- **`url` string:** Preview URL to screenshot instead of the test's URL, for this run only.
- **`repo` string:** GitHub repository in owner/name form, to report the result as a check.
- **`commit` string:** Head commit SHA the check is posted on. Required with repo.
- **`pr` integer:** Pull request number, for the summary comment on the pull request.
- **`branch` string:** Git branch name.

POST `/v1/visual/tests/{id}/run`
[cURL](https://testingbot.com#)
Request

```bash
$ 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"
```

Response

```json
{
  "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"
}
```

GET `/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

- **`check` string required:** Check id returned when the check was started.

### Response fields

- **`check` string:** Check id.
- **`test_id` integer:** The visual test.
- **`url` string:** The preview URL; null when the check ran the test's own URL, or once the check is older than 7 days.
- **`preview` boolean:** Whether a preview URL replaced the test's URL.
- **`state` string:** `running` until every browser finished, then `done`.
- **`passed` boolean:** true when every browser compared and passed, false otherwise. null while `running`.
- **`test_url` string:** The visual test in the TestingBot dashboard.
- **`browsers` array of visual check browser objects:** One entry per browser of the test.

GET `/v1/visual/checks/{check}`
[cURL](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/visual/checks/{check}" \
-u key:secret
```

Response

```json
{
  "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"
    }
  ]
}
```

POST `/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 from `results`, 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

- **`url` string required:** The scanned page (http, https or file URL), at most 2048 characters.
- **`results` json required:** The axe-core result object (with `violations`, `incomplete` and `passes`).
- **`standard` string:** Standard the scan ran against.
- **`title` string:** Page title.
- **`scope` string:** `page`, or `selection` when only one element was scanned.
- **`browser` string:** Browser the scan ran in.
- **`extension_version` string:** Version of the extension that sent it.
- **`viewport_width` integer:** Viewport width in CSS pixels.
- **`viewport_height` integer:** Viewport height in CSS pixels.
- **`keyboard` json:** Result of the extension's keyboard check (tab order, traps).
- **`context` json:** Scan context: selector of a scanned selection, axe options, frames scanned, and the scroll offset and device pixel ratio of a screenshot.
- **`screenshot` string:** The visible part of the page as a base64 JPEG or PNG (a `data:` URL is accepted too), at most 2 MB decoded.

POST `/v1/accessibility/scans`
[cURL](https://testingbot.com#)
Request

```bash
$ 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)"'}'
```

Response

```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
}
```

GET `/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 but `saved_this_month` is null. 
### Response fields

- **`monthly_limit` integer:** Scans the account can save per calendar month (UTC); null when unlimited.
- **`saved_this_month` integer:** Scans saved this calendar month.
- **`saves_left` integer:** Saves left this month; null when unlimited.
- **`upgrade_url` string:** Where to raise the limit; null when unlimited.

GET `/v1/accessibility/scans/quota`
[cURL](https://testingbot.com#)
Request

```bash
$ curl "https://api.testingbot.com/v1/accessibility/scans/quota" \
-u key:secret
```

Response

```json
{
  "monthly_limit": 10,
  "saved_this_month": 3,
  "saves_left": 7,
  "upgrade_url": "https://testingbot.com/pricing"
}
```

[Previous User & Team Management](https://testingbot.com/support/api/user) [Next Insights](https://testingbot.com/support/api/insights)
