---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Cloud Runner Test Runner REST API

# Cloud Runner Test Runner REST API {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 7 minutes to read

Manages tests to be executed in a cloud runner for Automated Test Framework (ATF).
The Cloud Runner Test Runner API requires the [ATF Test Generator and Cloud Runner](https://www.servicenow.com/docs/access?context=atf-tg-cr-intro&version=xanadu&pubname=xanadu-servicenow-platform&ft:locale=en-US) (sn_atf_tg) plugin. The methods available with this API run in the now namespace and can be called using API Name,
One-click regression testing for ATF, in the REST API Explorer. The
admin role is required to access this API.  
You can use this API for the following tasks:

* Start an ATF test or test suite in the Cloud Runner browser.
* Check the progress of the test job.
* Cancel the test job.
{#cloudrunner-testrunner-api__cloudrnr-TestRunnerAPI-scoped_ul_vwb_wvn_31c}

The Cloud Runner Test Runner API may be used in tandem with the [Cloud Runner Test Generation REST API](https://servicenow-prod.fluidtopics.net/5qhFvUFabNBrgM2O~A8heQ#cloudrunner-testgeneration-api "Manages test job generation to be executed in a cloud runner for Automated Test Framework (ATF).") and [Cloud Runner Test User REST API](https://servicenow-prod.fluidtopics.net/R91Ur5YEmltpH6bfwu0NhQ#cloudrunner-testuser-api "Manages test user jobs to be executed in a cloud runner for Automated Test Framework (ATF)."). For
instance, you can generate a test (Cloud Runner Test Generation API) and then get the progress
of the test in the browser orchestration queue (Cloud Runner TEST Generation API) and check the
number of tests that passed or failed.

To view the Server API reference documentation of this API, see [Cloud Runner TestRunnerApi -- Scoped, Global](https://servicenow-prod.fluidtopics.net/1f_LUhgMcRemWk6yfAOi2g#cloudrnr-TestRunnerAPI-scoped "Manages tests to be executed in a cloud runner for Automated Test Framework (ATF). This API is part of the CloudRunnerApi script include.").

## Cloud Runner Test Runner - GET /now/sn_atf_tg/test_runner_progress {#ariaid-title2}

Provides the status of each test ran for a provided Browser Orchestration Queue (BOQ) record.

### URL format

Default URL: GET /api/now/sn_atf_tg/test_runner_progress

### Supported request parameters

{#cr-TestRunnerAPI-GET-test-run-progress__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 1. Path parameters]

{#cr-TestRunnerAPI-GET-test-run-progress__entry__6}

| Name | Description |
|-|-|
| snboqId | Required. The BOQ record sys_id of the test runner job to get the progress of. Located in the BOQ \[sn_atf_tg_sn_boq\] table. Data type: String |
[Table 2. Query parameters]

{#cr-TestRunnerAPI-GET-test-run-progress__entry__10}

| Name | Description |
|-|-|
| None |   |
[Table 3. Request body parameters (XML or JSON)]

### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestRunnerAPI-GET-test-run-progress__entry__14}{#cr-TestRunnerAPI-GET-test-run-progress__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 4. Request headers]

{#cr-TestRunnerAPI-GET-test-run-progress__entry__18}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestRunnerAPI-GET-test-run-progress__table_vdy_gwz_31c__entry__2}

| Status code | Description |
|-|-|
| 200 | Successfully retrieved the progress of the BOQ job. |
| 400 | Error getting BOQ record status. Returns one of the following messages: * No BOQ ID passed in -- No BOQ ID was provided. Add the BOQ ID to the request body. * Unable to find BOQ record -- Invalid Sys ID. Verify that the sys_id of the BOQ record is valid and the record exists. {#cr-TestRunnerAPI-GET-test-run-progress__ul_d5p_btk_p1c} |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 6. Status codes]

{#cr-TestRunnerAPI-GET-test-run-progress__table_vdy_gwz_31c}

### Response body parameters (JSON or XML)

{#cr-TestRunnerAPI-GET-test-run-progress__entry__30}

| Name | Description |
|-|-|
| result | Object containing the progress results of the test runner job or a message explaining why the request failed. Data type: Object "result": { "progress": 100, "state": "completed" } Or: { "result": { "message": "String" } } |
| result.message | Error message detailing why the test runner progress cannot be retrieved. The message parameter is not returned in a successful response. Data type: String |
| result.progress | A percentage indicating how close to completion a test is while in a running state. Data type: Number |
| result.state | The current status of the BOQ record. Possible values: * Pending -- The requested test activity has been created and waiting to be executed. * Processing -- The instance is scanning for records to ensure that the execution trackers are marked for cloud runner before the request is sent to the cloud infrastructure. * Browsers requested -- A request has been sent to the cloud infrastructure to start browsers for test generation or test running. * Running -- Cloud infrastructure browsers find and execute pending tests. * Completed -- The test task is complete. * Failed state -- The test task failed. {#cr-TestRunnerAPI-GET-test-run-progress__ul_hph_y5h_41c} Data type: String |
[ ]

### cURL request

The following request retrieves the test runner job progress of the BOQ record.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_runner_progress?snboqId=<sys_id of SNBOQ record>" \ 
    --request GET \ 
    --header "Accept:application/json" \ 
    --user "username:password"

The response indicates that the test is 100% complete.

    { 
      "result": { 
        "progress": 100, 
        "state": "completed" 
      } 
    }

The following example returns a 400 error message when no BOQ ID is passed.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_runner_progress" \
    --request GET \
    --header "Accept:application/json" \
    --user "username:password"

Response:

    {
      "result": {
        "message": "No SNBOQ ID passed in, add snboqId to request body"
      }
    }

The following example returns a 400 error message when an invalid BOQ ID is passed.

    curl "http://instance.service-now.com/api/now/sn_atf_tg/test_runner_progress?snboqId=invalid_sys_id" \
    --request GET \
    --header "Accept:application/json" \
    --user "username:password"

Response:

    {
      "result": {
        "message": "Invalid SNBOQ sys_id passed in"
      }
    }

## Cloud Runner Test Runner - POST /now/sn_atf_tg/cancel_test_runner {#ariaid-title3}

Sets the test runner job to complete status and cancels the root trackers of any generated tests that are running.

### URL format

Default URL: GET
/now/sn_atf_tg/cancel_test_runner

### Supported request parameters

{#cr-TestRunnerAPI-POST-cancel-test-runner__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 7. Path parameters]

{#cr-TestRunnerAPI-POST-cancel-test-runner__entry__6}

| Name | Description |
|-|-|
| None |   |
[Table 8. Query parameters]

{#cr-TestRunnerAPI-POST-cancel-test-runner__entry__10}

| Name | Description |
|-|-|
| snboqId | Sys_id of the Browser Orchestration Queue (BOQ) record (sn_atf_tg_sn_boq) associated with the test runner job to cancel. Located in the BOQ \[sn_atf_tg_sn_boq\] table. |
[Table 9. Request body parameters (XML or JSON)]

### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestRunnerAPI-POST-cancel-test-runner__table_ism_z2j_41c__entry__2}{#cr-TestRunnerAPI-POST-cancel-test-runner__accept-RESTAPI}{#cr-TestRunnerAPI-POST-cancel-test-runner__content_type-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
| Content-Type | Data format of the request body. Supported types: application/json or application/xml. Default: application/json |
[Table 10. Request headers]

{#cr-TestRunnerAPI-POST-cancel-test-runner__table_ism_z2j_41c} {#cr-TestRunnerAPI-POST-cancel-test-runner__entry__20}

| Header | Description |
|-|-|
| None |   |
[Table 11. Response headers]

### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestRunnerAPI-POST-cancel-test-runner__entry__24}{#cr-TestRunnerAPI-POST-cancel-test-runner__entry-200-status-code}

| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 400 | Error canceling job. Returns one of the following messages: * No BOQ ID passed in -- No BOQ ID was provided. Add the BOQ ID to the request body. * Unable to find BOQ record -- Invalid Sys ID. Verify that the sys_id of the BOQ record is valid and the record exists. {#cr-TestRunnerAPI-POST-cancel-test-runner__ul_fzp_ztk_p1c} |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 12. Status codes]

### Response body parameters (JSON or XML)

{#cr-TestRunnerAPI-POST-cancel-test-runner__entry__32}

| Name | Description |
|-|-|
| result | Object containing the results of the request. "result": { "message": String } {#cr-TestRunnerAPI-POST-cancel-test-runner__codeblock_hhp_4k2_p1c} Data type: Object |
| result.message | Message detailing whether the test cancellation was successful. Data type: String |
[ ]

### cURL request

The following example shows how to form a cancel test runner request according to the
sys_id of the BOQ record.

    curl "https://instance.service-now.com/api/now/sn_atf_tg/cancel_test_runner" \ 
    --request POST \ 
    --header "Accept:application/json" \ 
    --header "Content-Type:application/json" \ 
    --data "{\"snboqId\":\"<sys_id of BOQ record>\"}" \ 
    --user "username:password"

The response message indicating that the test runner is successfully canceled.

    { 
      "result": { 
        "message": "success" 
      } 
    } 

## Cloud Runner Test Runner - POST /now/sn_atf_tg/test_runner {#ariaid-title4}

Inserts a test runner job into the BOQ \[sn_atf_tg_sn_boq\] table for given test or test
suite, which is then run on the cloud runner.

### URL format

Default URL: POST
api/now/sn_atf_tg/test_runner

### Supported request parameters

{#cr-TestRunnerAPI-POST-test-runner__entry__2}

| Name | Description |
|-|-|
| None |   |
[Table 13. Path parameters]

{#cr-TestRunnerAPI-POST-test-runner__entry__6}

| Name | Description |
|-|-|
| None |   |
[Table 14. Query parameters]

{#cr-TestRunnerAPI-POST-test-runner__entry__10}

| Name | Description |
|-|-|
| testId | Sys_id of the test \[sys_atf_test\] or test suite \[sys_atf_test_suite\] to run on the cloud runner. |
[Table 15. Request body parameters (XML or JSON)]

### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestRunnerAPI-POST-test-runner__table_gcx_1fj_41c__entry__2}{#cr-TestRunnerAPI-POST-test-runner__accept-RESTAPI}{#cr-TestRunnerAPI-POST-test-runner__content_type-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
| Content-Type | Data format of the request body. Supported types: application/json or application/xml. Default: application/json |
[Table 16. Request headers]

{#cr-TestRunnerAPI-POST-test-runner__table_gcx_1fj_41c} {#cr-TestRunnerAPI-POST-test-runner__entry__20}

| Header | Description |
|-|-|
| None |   |
[Table 17. Response headers]

### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#cr-TestRunnerAPI-POST-test-runner__entry__24}

| Status code | Description |
|-|-|
| 200 | Successfully inserted a test runner BOQ job. |
| 400 | Error starting the test runner job. Returns one of the following messages: * Unable to find test or test suite with Sys ID \<testId\> -- Invalid test ID. Ensure that the sys_id of the test (sys_atf_test) or test suite (sys_atf_test_suite) record is valid and the record exists. * No Test ID passed in -- No test ID was passed. Add the test ID to the request body. {#cr-TestRunnerAPI-POST-test-runner__ul_uht_ttk_p1c} |
| 403 | Error granting user access to the endpoint. Ensure that the user has the admin role. |
[Table 18. Status codes]

### Response body parameters (JSON or XML)

{#cr-TestRunnerAPI-POST-test-runner__entry__32}

| Name | Description |
|-|-|
| result | Object containing the results of the request. { "result": { "snboqId": "String" } } {#cr-TestRunnerAPI-POST-test-runner__codeblock_n5d_sxk_p1c} Or: "result": { "message": "String" } {#cr-TestRunnerAPI-POST-test-runner__codeblock_hhp_4k2_p1c} Data type: Object |
| result.snboqId | Sys_id of the BOQ record that is inserted when test runner starts. Located in the BOQ \[sn_atf_tg_sn_boq\] table. |
| result.message | Error message detailing why the test runner cannot be started. |
[ ]

### cURL request

The following request inserts a test runner job into the BOQ \[sn_atf_tg_sn_boq\] table.

    curl "https://instance.service-now.com/api/now/sn_atf_tg/test_runner" \ 
    --request POST \ 
    --header "Accept:application/json" \ 
    --header "Content-Type:application/json" \ 
    --data "{\"testId\":\"<sys_id of ATF test or test suite>\"}" \ 
    --user "username:password"

The response body returns the sys_id of the test runner job that was successfully
inserted.

    { 
      "result": { 
        "snboqId": "<sys_id of newly inserted SNBOQ record>" 
      } 
    }

{#cr-TestRunnerAPI-POST-test-runner__codeblock_bhq_np3_41c}