---
title: "Allocate a device and create a new session"
method: POST
path: "/sessions"
tags: ["Session Lifecycle"]
---

# Allocate a device and create a new session

`POST /sessions`

## Request

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

Creates a new device session. The session runs on a private device or on a public device from the shared Sauce Labs cloud, depending on which
devices match your query.

## Request body

- object
  - `device` object
    - `deviceName` string: Device identifier (supports regex). If omitted, any device will be selected. Matches both descriptor and deviceName fields.
    - `os` 'android' | 'ios': Filter by operating system (Android or iOS). The enum is case insensitive.
  - `configuration` object
    - `tunnel` TunnelConfiguration
      - `name` string, required: Name of Sauce Connect tunnel to be used in this session
      - `owner` string: Owner of Sauce Connect tunnel, if not current user
    - `sessionDuration` string, ISO-8601: Session duration in ISO-8601 format. Sets the expiresAt timestamp; sessions will be forcefully closed after that time. Default: 6 hours. Max: 24 hours on private devices, 1 hour on public devices. A duration above the maximum your session qualifies for is capped rather than rejected, so read `expiresAt` from the response to see when the session actually ends. Sessions longer than 6 hours may be forcefully closed before expiresAt. Required when `autoStartTest` is set, where the maximum is 30 minutes (`PT30M`).
  - `autoStartTest` 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`

Ok

- SessionCreation
  - `id` string
  - `state` 'PENDING' | 'CREATING' | 'ACTIVE' | 'CLOSING' | 'CLOSED' | 'ERRORED'

## Other responses

- `400`: Bad Request
- `409`: Returned when your organization has no Access API concurrency left for the device class the session would run on. Public and private devices are entitled separately and counted separately, so running out on one class does not affect the other. A device is released when the session holding it is closed or expires. Which of the two bodies you get depends on your plan: organizations with a paid Access API entitlement on the device class get `Access API Concurrency Limit Reached`, and organizations without one fall back to the free tier and get `Free Tier Concurrency Limit Reached`.

---

[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)