These endpoints list the device groups and configurations a session can request. Authentication, error shapes and rate limits are covered in the REST API overview.
List Devices
List devices registered with the platform. Only online devices are returned: available, busy or updating.
GET /api/v1/devices/Auth: Bearer token required.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
device_type | string | Filter by ios, android or roku (Apple TV is ios and Android TV is android, both with category tv) |
category | string | Filter by phone, tablet, or tv |
Any other device_type or category value returns 422.
Response:
[
{
"id": 1,
"device_id": "ABCD1234-...",
"worker_id": "worker-3f9a1c2e",
"name": "iPhone 16",
"type": "ios",
"category": "phone",
"os_version": "iOS 18.0",
"status": "available",
"form_factor": null,
"display_metrics": {
"chrome": "phone13",
"scale": 3,
"screen": { "width": 390, "height": 844 },
"corners": { "ul": 47.33, "ur": 47.33, "ll": 47.33, "lr": 47.33 }
}
}
]| Field | Description |
|---|---|
id | Numeric device id. |
device_id | String device identifier. Use it for GET /devices/{device_id}, as device_id when starting a session, or as device_id on the CI run endpoints. |
worker_id | An opaque, stable label. Devices with the same label run on the same host; the value carries no other meaning. |
name | Device name. |
type | ios, android or roku. |
category | phone, tablet or tv. |
os_version | OS version, as shown in the dashboard. |
status | available, busy, or updating when the device is being updated or restarted and takes no new session yet. A session started on an updating device waits in the queue (with queue_reason devices_updating) and starts when the update ends. |
form_factor | foldable for a device whose display folds (for example the iPhone Duo or the Pixel 9 Pro Fold), otherwise null. |
display_metrics | The device’s screen geometry, or null when it isn’t known for this device. screen is the size in points, scale converts points to pixels, corners gives the screen’s corner radii in points, and chrome names the device frame the dashboard draws around the stream. A foldable adds panels (the cover and inner screens, each with the same fields) and posture_ranges, which lists the hinge angles that read as closed, partial and open on that device: each range’s min is included and its max is not (except 180). A range where the device can also settle in another posture, depending on how the hinge moved, names that posture as alternate (the iPhone Duo between 1 and 169 degrees). |
List Device Pools
Grouped view of the device list: one entry per (model, OS version, platform, category) combination, with availability counts. This is what the session-start device picker uses.
GET /api/v1/devices/poolsAuth: Bearer token required.
Response:
[
{
"group_key": "ios|phone|iPhone 16|18.0",
"model": "iPhone 16",
"os_version": "18.0",
"device_type": "ios",
"category": "phone",
"total": 4,
"free": 3,
"form_factor": null,
"display_metrics": { "chrome": "phone13", "scale": 3, "screen": { "width": 390, "height": 844 }, "corners": { "ul": 47.33, "ur": 47.33, "ll": 47.33, "lr": 47.33 } }
}
]device_type is ios, android or roku. form_factor and display_metrics have the same meaning as on List Devices.
Groups whose devices are all currently unreachable are omitted; they reappear when capacity returns.
Get Device
GET /api/v1/devices/{device_id}Auth: Bearer token required.
device_id is the string device identifier (the device_id field from the list response, not the numeric id).
Response: A single device object (same shape as the list entries).
Errors:
404— Device not found.