Tests API

Execute tests and get the status of individual test runs.

List all tests

Returns a list of test descriptions containing the test’s id, name, created timestamp, and folders.

REQUEST

GET https://api.reflect.run/v1/tests

RESPONSE

{
  "tests": [
    {
      "id": 3072323,
      "name": "Registration Flow",
      "created": 1570546969108,
      "folders": [
        "regression-tests"
      ]
    }
  ]
}

RESPONSE FIELDS

tests object: A list of test descriptions, including the test's id, name, and folders.

Run a test

Immediately schedules a test.

The browser field lets you specify which browser to run the test in. Supported values are: Chrome, Edge, Firefox, and Safari - if no value is specified Chrome is used.

Note

Your account must have access to the requested browser - requesting an unsupported browser will return a 400 error code.

Reflect identifies certain properties of the execution as “reserved”. These reserved fields can be overridden with values provided by the API request:

  • hostnames: Allows you to specify a replacement hostname value for a given target hostname. You can also optionally specify a new port by including it in the replacement (see below for an example). If your override specifies a port, note the following behavior:

    • If original includes a port value, it will only be applied on URLs of the test that also use that same port. For example, an original value of example.com:1234 would have no effect on https://example.com or https://example.com:5678.

    • If original does not include a port value, it will match every URL of the test that uses the same hostname, regardless of port. For example, an original value of example.com would match both https://example.com and https://example.com:1234.

    • If a port was specified in the URL of the test, it will be preserved unless a new value is specified in replacement or original included the port and replacement did not - in that case no port would be included in the resulting URL.

  • agent: Allows you to select a specific Tunnel to run the test through by specifying the agent’s name.

  • parameters: Allows you to specify a URL parameter key/value pair that will be included (or overwritten) on the test’s initial URL.

  • cookies: Allows you to specify cookies that will be set when loading the test’s initial URL. A cookie consists of the following fields:

    • name (required string): The name of the cookie to be set.

    • value (required string): The cookie’s value.

    • domain (optional string): Host to which the cookie will be sent. Defaults to the host of the test’s initial URL.

    • expires (optional number): Epoch timestamp (in milliseconds) indicating when the cookie should be deleted. If unspecified, the cookie becomes a session cookie.

    • httpOnly (optional boolean): Indicates the cookie should be inaccessible to JavaScript on the page and only sent to the server.

    • maxAge (optional number): Number of milliseconds until the cookie expires. If both expires and maxAge are set, maxAge has precedence.

    • path (optional string): A URL path that must exist in a request URL in order to include the cookie in a request.

    • secure (optional boolean): Indicates that the cookie should only be sent to the server when a request is made with https:.

  • headers: Allows you to specify headers that will be sent when loading the test’s initial URL.

    • name (required string): The name of the header.

    • value (required string): The header value.

    • persist (optional boolean): Specifies whether this header should only be set in the initial request or for every subsequent HTTP request (ex: when overriding the Accept-Language header). If set to true, the Authorization header is only set for requests that match the hostname of the test’s original URL. Defaults to false.

  • localStorage and sessionStorage: Allows you to specify local and session storage values to be set on the test’s initial URL.

The variables field allows you to specify a definition for a variable used in the test.

REQUEST

POST https://api.reflect.run/v1/tests/<test-id>/executions
{
  "browser": "Chrome",
  "overrides": {
    "agent": {
      "name": "agent-name"
    },
  
     "hostnames": [{
      "original": "prod.myapp.com",
      "replacement": "staging.myapp.com:1234"
    }],
    "parameters": [{
      "key": "token",
      "value": "abcdef"
    }],
    "cookies": [{
      "name": "my-favorite-cookie",
      "value": "chocolate-chip",
      "domain": "myapp.com",
      "expires": 123456789,
      "httpOnly": false,
      "maxAge": 123,
      "path": "/",
      "secure": true
    }],
    "headers": [{
      "name": "X-Custom-Header",
      "value": "custom-value"
    }],
    "localStorage": [{
      "key": "my-local-key",
      "value": "local-value"
    }],
    "sessionStorage": [{
      "key": "my-session-key",
      "value": "session-value"
    }]
  },
  "variables": {
    "username1": "user+${alpha(8)}@example.com",
    "password": "acompletelyunguessablepassword"
  },
  "emailFailures": true
}

REQUEST FIELDS

overrides optional object: Overrides to apply to properties of the test being executed.

  • agent (object, optional)

    • name (string, required) — The name of the Tunnel/Agent to use for this execution.

variables optional object: Collection of ('name', 'definition') variable overrides to apply to this scheduled execution.

emailFailures optional boolean: Controls whether email notifications should be sent for a failed test run. The default is true.

RESPONSE

{
  "executionId": 8939
}

RESPONSE FIELDS

executionId number: An identifier for the scheduled execution created by the request.

Get test runs

Returns the account's test runs, most recent first, with a stable cursor for pagination. Equivalent to the data shown on the app's Runs page.

REQUEST

GET https://api.reflect.run/v1/runs

Query parameters

  • limit (type: integer, optional) : Max runs to return. Default 25. Values above 100 are silently clamped to 100. Values ≤ 0 return a 400 Bad Request ("Limit must be positive.").

  • before (type: long, optional) : Cursor for pagination — pass the next value from a previous response of this endpoint to get the next page. Omit to get the most recent runs.

RESPONSE

{
  "runs": [
    {
      "runId": 20329304,
      "testId": 435411,
      "testName": "Login with valid credentials",
      "status": "passed",
      "variables": { "username": "[email protected]" },
      "overrides": null,
      "browser": "Chrome",
      "mobileDevice": null,
      "apiContext": null,
      "suiteId" : null,
      "isSuiteRerun" : null,
      "suiteExecutionId": null,
      "runBy": "Jane Doe",
      "startTime": 1757678400000,
      "endTime": 1757678415000,
      "runTime": 15000,
      "videoUrl": "https://.../video/20329304_abc123.mp4",
      "url": "https://app.reflect.run/tests/435411/runs/20329304?accountId=10792"
    }
  ],
  "next": 1757678000123456
}

Each run object — identical shape to the run object nested in GET /api/executions/:executionId

Pagination notes

  • Runs are ordered by creation time, most recent first

  • next is only returned when the page is full (i.e., there may be more runs behind it). A partial page means you've reached the end.

  • The cursor is in the run's created timestamp in epoch microseconds - pass it straight through in the next request to this endpoint.

  • Only runs within the account's data retention window are returned.

Get execution status

Returns a list of test result objects. The test result object includes the test’s id and a status field describing whether the test is “queued”, “running”, “succeeded”, or “failed”. Additionally, it contains a run object describing the properties of the test run such as its starting and ending time, and its video URL.

REQUEST

GET https://api.reflect.run/v1/executions/<execution-id>

RESPONSE

{
  "executionId": 17671,
  "browser": "Edge",
  "tests": [
    {
      "testId": 1690,
      "status": "succeeded",
      "run": {
          "runId": 20329304,
          "testId": 435411,
          "testName": "Login with valid credentials",
          "status": "passed",
          "variables": { "username": "[email protected]" },
          "overrides": null,
          "browser": "Chrome",
          "mobileDevice": null,
          "apiContext": null,
          "suiteId" : 123456,
          "isSuiteRerun" : true,
          "suiteExecutionId": null,
          "runBy": "API/Scheduler",
          "startTime": 1757678400000,
          "endTime": 1757678415000,
          "runTime": 15000,
          "videoUrl": "https://.../video/20329304_abc123.mp4",
          "url": "https://app.reflect.run/tests/435411/runs/20329304?accountId=10792"
     }
    }
  ]
}

RESPONSE FIELDS

executionId number: An identifier for the scheduled execution.

browser string: The browser that the tests in the scheduled execution are configured to run on.

tests object: List of test results, including the testId and status.

tests.testId number: An identifier for the test.

tests.status string: One of: queued, running, succeeded, or failed. Summarizes the outcome of the test instance from its runs.

tests.run object: The test run from this execution.

tests.run.runId number: An identifier for the test run.

tests.run.testName string: Name of the test.

tests.run.overrides object: Overrides applied to this run (same structure as the overrides object documented under Run a test → Request fields)

tests.run.browser string: Browser the run used — one of Chrome, ChromeLatestMinus1, ChromeLatestMinus2, Firefox, Safari, Edge. Mutually exclusive with mobileDevice and apiContext.

tests.run.mobileDevice object: Device/app configuration used, present only for native-mobile runs. Internal structure, varies by device provider.

tests.run.apiContext object: Present only for API test runs. Currently always {}.

tests.run.suiteId string: Present when the test run was run as a part of a suite. Use this value with the suiteExecutionId to determine how to call the suite execution API to get test results

tests.run.isSuiteRerun boolean: true if this test run was retried as a part of a suite execution.

tests.run.suiteExecutionId long: ID of the suite execution this run belongs to, if it was a part of one.

tests.run.runBy string: Name of the user who started the run. "API/Scheduler" if the run wasn't started by a user (started via API or on a schedule). Unknown user if the user who started it can no longer be found in the account.

tests.run.status string: The outcome of the test run. Either passed or failed.

tests.run.variables object: The variables that were used or created by the test run.

tests.run.startTime number: Timestamp of when the test run started.

tests.run.endTime number: Timestamp of when the test run stopped.

tests.run.runTime number: Total time that the test run spent running (endTime - startTime).

tests.run.videoUrl string: The URL of a video recording of the test run.

Get Test Detail

Returns the full step-by-step definition of a single test, including any segments it references.

Request

GET https://api.reflect.run/v1/tests/<test-id>

Path parameters

  • test-id (integer) The Test ID (visible in the Reflect app URL when viewing the test).

    Steps that reference a Reflect Segment appear with "type": "segment" and include the segment's id and name. To get the steps inside a referenced segment, call GET https://api.reflect.run/v1/segments and look it up by ID.

Response

{
    "id": 98765,
    "name": "End-to-end checkout",
    "description": "Full purchase flow against staging",
    "steps": [
      {
        "type": "segment",
        "id": 12345,
        "name": "Login flow"
      },
      {
        "type": "direct-navigation",
        "url": "https://staging.example.com/products/42"
      },
      {
        "type": "click",
        "description": "Add to cart",
        "selector": "[data-test='add-to-cart']"
      },
      {
        "type": "prompt",
        "description": "Validate that one item is in the shopping cart"
      },
      {
        "type": "api",
        "httpMethod": "POST",
        "url": "https://api.example.com/coupons/redeem",
        "requestBody": "{\"code\":\"WELCOME10\"}"
      },
      {
        "type": "visual-validation",
        "selector": ".order-confirmation"
      }
    ],
    "parameters": [
      { "name": "checkout_amount", "value": "49.99" }
    ]
  }

Create a test

Creates a new test

Note: SmartBear MCP server also supports this functionality with a corresponding create-test tool call such that AI Agents like Claude can build or import existing tests built on open source frameworks (Selenium, Cypress, Playwright) or in other SmartBear products (TestComplete, BearQ)

Request

POST https://api.reflect.run/v1/tests
Web Test example request body

{ 
    "name": "Comprehensive Web Test (docs)",  
    "type": "web",  
    "description": "A web test exercising every supported step type with all applicable fields.",  
    "deviceProfile": "desktop",  
    "steps": [    
        { "type": "browser-navigate", "description": "Go to the home page", "url": "https://example.com", "title": "Example Home" },    
        { "type": "segment", "id": 12345 },    
        { "type": "click", "description": "Click the login button", "selector": "#login", "tag": "button", "expectedText": "Log in" },    
        { "type": "visual-validation", "description": "Visually validate the hero section", "selector": ".hero", "tag": "section", "expectedText": "Welcome" },    
        { "type": "text-validation", "description": "Validate the status message text", "selector": ".msg", "tag": "span", "expectedText": "Success" },    
        { "type": "input", "description": "Enter the username", "selector": "#user", "tag": "input", "inputText": "alice", "expectedText": "Username" },    
        { "type": "rich-text-input", "description": "Enter the rich-text body", "selector": "#body", "tag": "div", "inputText": "hello world", "expectedText": "Body" },    
        { "type": "submit", "description": "Submit the form", "selector": "#form", "tag": "form", "expectedText": "Submit" },    
        { "type": "file-upload", "description": "Upload a file", "selector": "#file", "tag": "input", "expectedText": "Choose file" },    
        { "type": "scroll", "description": "Scroll the results list", "selector": ".list", "tag": "ul", "expectedText": "Results" },    
        { "type": "keyboard-shortcut", "description": "Send a keyboard shortcut", "selector": "body", "tag": "body", "inputText": "Ctrl+Shift+a", "expectedText": "Focused" },    
        { "type": "focus", "description": "Focus the email field", "selector": "#email", "tag": "input", "expectedText": "Email" },    
        { "type": "hover", "description": "Hover the menu", "selector": "#menu", "tag": "nav", "expectedText": "Menu" },    
        { "type": "alert", "description": "Accept the browser alert" },    
        { "type": "drag-and-drop", "description": "Drag an item", "selector": "#item", "tag": "li", "expectedText": "Item" },    
        { "type": "text-highlight", "description": "Highlight a paragraph", "selector": "#para", "tag": "p", "expectedText": "Paragraph" },    
        { "type": "browser-url-changed", "description": "Follow a link", "url": "https://example.com/page3", "title": "Page 3" },    
        { "type": "browser-back", "description": "Navigate back", "title": "Example Home" },    
        { "type": "browser-forward", "description": "Navigate forward", "title": "Page 3" },    
        { "type": "browser-refresh", "description": "Refresh the page", "title": "Page 3" },    
        { "type": "api", "description": "Call an API", "url": "https://api.example.com/orders", "httpMethod": "POST", "requestBody": "{\"a\":1}", "requestHeaders": [ { "name": "Content-Type", "value": "application/json" }, { "name": "Authorization", "value": "Bearer ${var(token)}" } ], "followRedirects": false },    
        { "type": "javascript", "description": "Run a JavaScript snippet", "script": "return document.title;" },    
        { "type": "prompt", "description": "Verify the dashboard loaded", "promptType": "action" },    
        { "type": "prompt", "description": "Is the form valid?", "promptType": "assert", "expectedResponse": true },    
        { "type": "prompt", "description": "What is the order total?", "promptType": "query", "expectedResponse": "42" },    
        { "type": "file-download", "description": "Download the report" },    { "type": "update-parameters", "description": "Update run parameters" },    
        { "type": "wait", "description": "Wait for animations", "seconds": 5 },    
        { "type": "receive-email", "description": "Wait for the welcome email", "email": { "text": "Welcome", "filters": { "fromAddress": "[email protected]", "fromName": "Example", "subject": "Welcome", "toAddress": "[email protected]" } } },    
        { "type": "receive-sms", "description": "Wait for the verification code", "sms": { "text": "Your code is 123456", "filters": { "fromNumber": "+15551230000", "toNumber": "+15559876543" } } }  ],  
    "parameters": [    
        { "name": "env", "value": "prod" },    
        { "name": "token", "value": "abc123" }  ]}

API Test example request body

{  
    "name": "Comprehensive API Test (docs)",  
    "type": "api",  "description": "An API test exercising every supported step type with all applicable fields.",  
    "steps": [    
        { "type": "segment", "id": 12345 },    
        { "type": "api", "description": "Call an API", "url": "https://api.example.com/orders", "httpMethod": "POST", "requestBody": "{\"a\":1}", "requestHeaders": [ { "name": "Content-Type", "value": "application/json" }, { "name": "Authorization", "value": "Bearer ${var(token)}" } ], "followRedirects": false },    
        { "type": "javascript", "description": "Run a JavaScript snippet", "script": "return 1 + 1;" },    
        { "type": "wait", "description": "Wait between calls", "seconds": 3 },    
        { "type": "update-parameters", "description": "Update run parameters" },    
        { "type": "receive-email", "description": "Wait for a notification email", "email": { "text": "Order created", "filters": { "fromAddress": "[email protected]", "fromName": "Example", "subject": "Order", "toAddress": "[email protected]" } } },    
        { "type": "receive-sms", "description": "Wait for an SMS notification", "sms": { "text": "Order 123 created", "filters": { "fromNumber": "+15551230000", "toNumber": "+15559876543" } } }  ],  
    "parameters": [    
        { "name": "env", "value": "prod" },    
        { "name": "token", "value": "abc123" }  ]}

Native mobile Test example request body

{  
    "name": "Comprehensive Mobile Test (docs)",  
    "type": "native-mobile",  
    "description": "A native-mobile test exercising every supported step type with all applicable fields.",  
    "steps": [    
        { "type": "segment", "id": 12345 },    
        { "type": "prompt", "description": "Tap the login button", "promptType": "action", "expectedResult": "The login screen is shown" },    
        { "type": "prompt", "description": "Is the user logged in?", "promptType": "assert", "expectedResponse": true, "expectedResult": "The home screen is shown" },    
        { "type": "prompt", "description": "What is the account balance?", "promptType": "query", "expectedResponse": "100.00", "expectedResult": "The balance is displayed" },    
        { "type": "text-validation", "description": "Validate the greeting text", "expectedText": "Welcome back" },    { "type": "rotate-device", "description": "Rotate the device" },    
        { "type": "set-device-location", "description": "Set the GPS location", "latitude": 37.7749, "longitude": -122.4194 },    
        { "type": "reset-device", "description": "Reset the app state" },    
        { "type": "deeplink", "description": "Open a deeplink", "url": "myapp://home" },    
        { "type": "appium", "description": "Run an Appium command", "command": "scroll", "argument": "{\"direction\":\"down\"}" },    
        { "type": "api", "description": "Call a backend API", "url": "https://api.example.com/orders", "httpMethod": "GET", "requestHeaders": [ { "name": "Accept", "value": "application/json" } ], "followRedirects": true },    
        { "type": "wait", "description": "Wait for the screen", "seconds": 2 },    
        { "type": "update-parameters", "description": "Update run parameters" },    
        { "type": "receive-email", "description": "Wait for the confirmation email", "email": { "text": "Confirmed", "filters": { "fromAddress": "[email protected]", "fromName": "Example", "subject": "Confirmation", "toAddress": "[email protected]" } } },    
        { "type": "receive-sms", "description": "Wait for the verification code", "sms": { "text": "Your code is 123456", "filters": { "fromNumber": "+15551230000", "toNumber": "+15559876543" } } }  ],  
    "parameters": [    
        { "name": "env", "value": "prod" },    
        { "name": "token", "value": "abc123" }  ]}

Request Fields

name (string, required): Name of the test

description (string, optional): description of the test

type (string, required): Supported values: web, api, native-mobile

steps: an ordered list of test steps

parameters: an optional set of parameters associated with the test. Each parameter can optionally have a default value.

Response

{"id":10,"url":"https://app.reflect.run/tests/1234/definition?accountId=123"}
In this section:
© 2026
Publication date: