Start Session

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:

Create one allocation.

Start the first session with its allocationId.

Run the test and stop the session.

Start another session with the same allocationId.

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.

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
client.sessions().start(request)	await client.sessions().start(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
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.

{
  "allocationId": "allocation-123",
  "userId": 42,
  "userEmail": "[email protected]",
  "companyId": 7,
  "companyName": "Example Company",
  "videoRecording": true,
  "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.

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

Session session = client.sessions().start(
        DeviceStartSessionRequest.builder()
                .allocationId("allocation-123")
                .userId(42L)
                .userEmail("[email protected]")
                .companyId(7L)
                .companyName("Example Company")
                .videoRecording(true)
                .appiumVersion("2.5.0")
                .build()
);

System.out.println(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, videoRecordUrl

{
  "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": "[email protected]",
  "companyId": 7,
  "companyName": "Example Company",
  "deviceSerial": "R58M123456A",
  "deviceName": "Galaxy S23",
  "deviceModel": "SM-S911B",
  "deviceManufacturer": "Samsung",
  "devicePlatform": "Android",
  "deviceVersion": "14",
  "videoRecording": true,
  "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 for its documented values. Recording URLs can remain null until processing is complete.

Continue with your Appium test. When finished, call Stop Session.