---
title: "Start a test on a device session"
method: POST
path: "/sessions/{sessionId}/startTest"
tags: ["Test Results"]
---

# Start a test on a device session

`POST /sessions/{sessionId}/startTest`

## Request

- Base URL: `https://api.us-west-1.saucelabs.com/rdc/v2`
- URL: `https://api.us-west-1.saucelabs.com/rdc/v2/sessions/{sessionId}/startTest`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/saucelabs/apis/real-device-access-api-reference/docs/sessions/:sessionId/startTest/post.ts> (a function with typed inputs; its response is checked against the schema)

Starts a new test on the session. From this point on we start recording what happens on the device.
This lets you mark the start of a test that you are executing on the device. Afterwards you define
whether the test passed or failed, and you review it on the Test Results page in the Sauce Labs UI,
just like any other job you ran on Sauce Labs.

The response contains the `jobId`. Use the links returned by [`getTests`](#operation/getTests) to fetch the
report through the ['jobs' API](https://docs.saucelabs.com/dev/api/rdc/#jobs).

Only one test can be active on a session at a time — call [`endTest`](#operation/endTest) to finish the
current test before starting the next one. If you created the session with `autoStartTest`, a test is already
running on it, so end that one first or this call comes back as a `409`. A session can hold at most 500 tests.

Artifact capture (video, device logs, network capture, and so on) is opt-in: every toggle defaults to `false`.
Request the artifacts you need in the `artifacts` object and they are recorded for the duration of the test.

The request body is optional. If you omit it, the test is created with a generated name, no build,
no tags, and no artifacts.

## Path parameters

- `sessionId` string, required

## Request body

- StartTestRequest: Optional metadata and artifact toggles for the test. Every field is optional.
  - `testName` string: The name the test is shown under in the Sauce Labs UI. Defaults to a generated name.
  - `build` string: Build identifier used to group this test with other tests of the same build.
  - `tags` string[]: Tags to attach to the test, for filtering in the Sauce Labs UI.
  - `artifacts` ArtifactToggles: The artifacts to capture for the duration of the test. All toggles are opt-in and default to `false`.
    - `video` boolean: Record a video of the device screen.
    - `deviceLogs` boolean: Capture the device log (logcat on Android, syslog on iOS).
    - `networkCapture` boolean: Capture network traffic as a HAR file.
    - `screenshots` boolean: Collect the screenshots taken during the test.
    - `appiumLogs` boolean: Collect the log of the hosted Appium server, if one is running.

## Response `200`

Test started

- StartTestResponse
  - `jobId` string: The Sauce Labs job id of the test that was started. Use it to fetch the test and its artifacts from the jobs API.

## Other responses

- `400`: Bad Request
- `401`: Not Authorized
- `404`: Not Found
- `409`: The test could not be started or ended in the session's current state. This covers: - `Test already active.` — a test is still running on the session; call `endTest` before starting another. The response carries the offending id in `activeTestId`. - `Test limit reached.` — the session already holds the maximum of 500 tests; start a new session to record more. - `No active test.` — `endTest` was called on a session that has no running test. - `Test is not ready.` — the test is still being created; retry shortly.
- `500`: Internal Server Error

---

[API](https://skmtc.dev/saucelabs/apis/real-device-access-api-reference.md) - [All operations](https://skmtc.dev/saucelabs/apis/real-device-access-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/saucelabs/apis/real-device-access-api-reference/revisions/f845a4b66e37?raw)