--- title: Start Session slug: devicepark/sdk-documentation/sessions/start-session description: Start a Device Park session on an active allocation. docTags: createdAt: 2026-08-10T08:03:45.197Z --- A session represents one test interaction period on an allocated device. Create a session after the allocation has assigned a device. The session starts the Device Park/Appium runtime, but the SDK does not execute Appium commands. Use your normal Appium client after the session is ready. ## Before You Begin - Create an allocation and keep its `allocationId`. - Wait until Device Park assigns a device to the allocation. - Prepare the required user and company identifiers and names. - Decide whether the session must be recorded. - Use an Appium version supported by your Device Park environment, or leave it unset to use the environment default. ## Allocation Relationship `allocationId` connects the session to its reserved device. One active allocation can be reused for multiple sessions. A common sequence is: 1. Create one allocation. 2. Start the first session with its `allocationId`. 3. Run the test and stop the session. 4. Start another session with the same `allocationId`. 5. Release the allocation after the last session. Do not release the allocation between sessions. Whether sessions may run concurrently depends on the Device Park environment; the safe default is to stop one session before starting the next. :::hint{type="info"} You can create multiple sessions from one active allocation. Stop the current session before starting the next unless your Device Park administrator confirms concurrent-session support. ::: ## SDK Method | Java | Node.js | .NET | | ---------------------------------- | ---------------------------------------- | ------------------------------------------- | | `client.sessions().start(request)` | `await client.sessions().start(request)` | `await client.Sessions.StartAsync(request)` | ## Request Fields | Field | Required | Default | Description | | -------------------------- | -------- | ------------------- | ---------------------------------------------------------- | | `allocationId` | Yes | - | Active allocation identifier | | `userId` | Yes | - | Unique user identifier | | `userEmail` | Yes | - | User email address | | `companyId` | Yes | - | Unique company identifier | | `companyName` | Yes | - | Non-blank company name | | `videoRecording` | No | `false` | Enables session recording | | `videoRecordingScope` | No | `FULL_SESSION` | Java, Node.js and .NET. `FULL_SESSION` or `APPIUM_SESSION` | | `appiumVersion` | No | Environment default | Requested Appium version | | `companyPoolId` | No | - | Company pool context | | `customVideoRecordingPath` | No | - | Custom recording path | ## Request Mapping The SDK sends the built request as a JSON body. OAuth authorization and JSON content headers are managed by the SDK client. ```json { "allocationId": "allocation-123", "userId": 42, "userEmail": "qa@devicepark.testinium.io", "companyId": 7, "companyName": "Example Company", "videoRecording": true, "videoRecordingScope": "FULL_SESSION", "appiumVersion": "2.5.0" } ``` `sessionId` is not a request field. Device Park generates it when the session starts and returns it in the response. Unset optional builder fields are omitted, and `videoRecording` defaults to `false`. The Java SDK sends `videoRecordingScope` on every start request. Import `io.testinium.devicepark.model.sessions.VideoRecordingScope`. `FULL_SESSION` lets Device Park start and stop recording for the whole session. `APPIUM_SESSION` leaves recording start and stop to Appium plugins. An unset Java builder value is `FULL_SESSION`. In Node.js, import `VideoRecordingScope` from `@device-park/public-sdk` and call `.videoRecordingScope(VideoRecordingScope.FULL_SESSION)`; when it is omitted the API applies `FULL_SESSION`. :::hint{type="warning"} Java SDK `1.0.1` still exposes a legacy `sessionId(...)` builder method and does not validate every required field during `build()`. Do not set `sessionId`. Always provide `allocationId`, `userId`, `userEmail`, `companyId` and a non-blank `companyName`; Device Park validates these fields when the request is received. ::: ## Examples :::CodeblockTabs ```java Session session = client.sessions().start( DeviceStartSessionRequest.builder() .allocationId("allocation-123") .userId(42L) .userEmail("qa@devicepark.testinium.io") .companyId(7L) .companyName("Example Company") .videoRecording(true) .videoRecordingScope(VideoRecordingScope.FULL_SESSION) .appiumVersion("2.5.0") .build() ); System.out.println(session.sessionId()); ``` ```typescript import { DeviceStartSessionRequestBuilder } from "@device-park/public-sdk"; const session = await client.sessions().start( new DeviceStartSessionRequestBuilder() .allocationId("allocation-123") .userId(42) .userEmail("qa@devicepark.testinium.io") .companyId(7) .companyName("Example Company") .videoRecording(true) .appiumVersion("2.5.0") .build() ); console.log(session.sessionId); ``` ```csharp var session = await client.Sessions.StartAsync( new DeviceStartSessionRequest.Builder() .AllocationId("allocation-123") .UserId(42) .UserEmail("qa@devicepark.testinium.io") .CompanyId(7) .CompanyName("Example Company") .VideoRecording(true) .VideoRecordingScope(VideoRecordingScope.FULL_SESSION) .AppiumVersion("2.5.0") .Build()); Console.WriteLine(session.SessionId); ``` ::: ## Result The method returns one `Session`. Store `sessionId`; it is required to stop the session, download the Appium log and list screen records. | Field group | Fields | | ---------------- | ------------------------------------------------------------------------------------------------------- | | Identity | `id`, `sessionId`, `allocationId`, `client` | | Lifecycle | `state`, `startDate`, `endDate`, `latestInteractionTime`, `createdAt`, `updatedAt`, `dataAccessEndDate` | | Device | `deviceSerial`, `deviceName`, `deviceModel`, `deviceManufacturer`, `devicePlatform`, `deviceVersion` | | User/company | `userId`, `userEmail`, `companyId`, `companyName` | | Runtime/evidence | `appiumVersion`, `videoRecording`, `videoRecordingScope`, `videoRecordUrl` | ```json { "id": 1001, "state": "ACTIVE", "client": null, "sessionId": "session-123", "allocationId": "allocation-123", "startDate": "2026-07-28T10:00:00Z", "endDate": null, "latestInteractionTime": "2026-07-28T10:00:00Z", "userId": 42, "userEmail": "qa@devicepark.testinium.io", "companyId": 7, "companyName": "Example Company", "deviceSerial": "R58M123456A", "deviceName": "Galaxy S23", "deviceModel": "SM-S911B", "deviceManufacturer": "Samsung", "devicePlatform": "Android", "deviceVersion": "14", "videoRecording": true, "videoRecordingScope": "FULL_SESSION", "videoRecordUrl": null, "appiumVersion": "2.5.0", "createdAt": "2026-07-28T10:00:00Z", "updatedAt": "2026-07-28T10:00:00Z", "dataAccessEndDate": null } ``` `state` is a server-provided string; see [List Sessions](docId\:yDnbFyoHkKjGUefb_-6rf) for its documented values. Recording URLs can remain `null` until processing is complete. Continue with your Appium test. The Java and Node.js SDKs can [open the device screen stream](docId\:sMdrq_2Jfb0NIyvLPCtpD) with the returned `sessionId`. When finished, call [Stop Session](docId\:BS_aoo0s5DDTONHvueqQr).