Tests & Builds API | TestingBot API Documentation

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
        .NET
        Ruby
        Python
        PHP
        Java
        NodeJS
    Request

        
  
  $ 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, limit });

    Response

  
  {
  "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
        .NET
        Ruby
        Python
        PHP
        Java
        NodeJS
    Request

        
  
  $ 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);

    Response

  
  {
  "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
        .NET
        Ruby
        Python
        PHP
        Java
        NodeJS
    Request

  $ 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);

    Response

  {
  "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
        .NET
        Ruby
        Python
        PHP
        Java
        NodeJS
    Request

  $ 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);

    Response

  {
  "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
    Request

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

    Response

  
  {
  "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
    Request

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

    Response

  { "success": true }

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
        .NET
        Ruby
        Python
        PHP
        Java
        NodeJS
    Request

  $ 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);

    Response

  {
  "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.

Arguments

ids array required: Up to 25 numeric test IDs or WebDriver session_ids.

    DELETE
    /v1/tests
  
        cURL
    Request

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

    Response

  { "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
        PHP
        Java
    Request

        
  
  $ 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);

    

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
    Request

  $ curl -X POST "https://api.testingbot.com/v1/tests/{id}" \
-u key:secret

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
        .NET
        Ruby
        Python
        PHP
        Java
        NodeJS
    Request

        
  
  $ 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(offset, limit);

    Response

  
  {
  "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).

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
        .NET
        Ruby
        Python
        PHP
        Java
        NodeJS
    Request

        
  
  $ 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);

    Response

  
  {
  "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
        .NET
        Ruby
        Python
        PHP
        Java
        NodeJS
    Request

  $ 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);

    Response

  {
  "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
    Request

        
  
  $ 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

  
  {
  "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).

Arguments

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

    DELETE
    /v1/builds
  
        cURL
    Request

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

    Response

  { "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
    Request

  $ 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
    Request

  $ 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
    Request

        
  
  $ 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

  
  {
  "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
    Request

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

    Response

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