How to Get User Device Details using API

Modified on Sun, Jun 14 at 1:51 PM

Overview

This API retrieves all Android and iOS devices available to the authenticated user. It returns detailed information about each device, including platform details, connectivity status, execution status, reservation status, and automation configuration.

This API can be used to:

Retrieve devices available for testing.
Verify device availability before execution.
Identify device status and connectivity issues.
Fetch Appium configuration details for automation.
Determine whether a device is currently reserved or in use.

Endpoint

URL: https://{your_base_url}.testgrid.io/api/get-user-devices

Method: POST

Request Parameters

Parameter	Type	Required	Description
user_token	String	Yes	User authentication token

Request

curl --location 'https://{your_base_url}.testgrid.io/api/get-user-devices'
--form 'user_token="YOUR_USER_TOKEN"'

Sample Response

{
"success": true,
"devices": {
"ios": [
{
"device_id": "38",
"UDID": "",
"tags": "",
"device_type": "1",
"platform_version": "16.5.1",
"device_name": "iPhone 12 Pro",
"manufactured_by": "",
"s_device": "BDQ82O",
"wda_local_port": "3009",
"system_port": "",
"is_run_generator": "0",
"is_run_build": "0",
"is_run_local_execution": "0",
"is_run_virtual_usb": "0",
"is_run_device_cloud": "0",
"is_offline": "0",
"is_connected": "1",
"is_device_offline": "0",
"is_unauthorised": "0",
"is_rebooting": "0",
"is_reserved": "0",
"is_preparing": "0",
"is_cleaning": "0",
"server_type": "1",
"reserved_device_user_email": "",
"appium_url": "",
"remotelite_url": "",
"platform_name": "iOS",
"automation_name": "XCUITest"
}
],
"android": [
{
"device_id": "34",
"UDID": "",
"tags": "Pixar 7",
"device_type": "2",
"platform_version": "13",
"device_name": "Pixel 7",
"manufactured_by": "",
"s_device": "AOAIG3",
"wda_local_port": "",
"system_port": "4016",
"is_run_generator": "0",
"is_run_build": "0",
"is_run_local_execution": "0",
"is_run_virtual_usb": "0",
"is_run_device_cloud": "0",
"is_offline": "0",
"is_connected": "1",
"is_device_offline": "0",
"is_unauthorised": "0",
"is_rebooting": "0",
"is_reserved": "0",
"is_preparing": "0",
"is_cleaning": "0",
"server_type": "1",
"reserved_device_user_email": "",
"appium_url": "",
"remotelite_url": "",
"platform_name": "Android",
"automation_name": "UiAutomator2"
}
]
},
"message": "Device Fetch Successfully."
}

Response Parameters

Top-Level Response Parameters

Parameter	Type	Description
success	Boolean	Indicates whether the request was successful
devices	Object	Contains iOS and Android device lists
message	String	Response message

Device Collection Parameters

Parameter	Type	Description
ios	Array	List of available iOS devices
android	Array	List of available Android devices

Basic Device Information

Parameter	Type	Description
device_id	String	Unique device identifier
UDID	String	Unique Device Identifier
tags	String	Custom tags assigned to the device
device_type	String	Device type (`1` = iOS, `2` = Android)
platform_name	String	Platform name (iOS or Android)
platform_version	String	Operating system version
device_name	String	Device name
manufactured_by	String	Device manufacturer
s_device	String	Internal TestGrid device identifier
server_type	String	Server type associated with the device

Automation Configuration

Parameter	Type	Description
automation_name	String	Automation framework configured for the device
appium_url	String	Appium server URL
remotelite_url	String	Device access URL
wda_local_port	String	WebDriverAgent port (iOS devices)
system_port	String	Appium system port (Android devices)

Execution Status Parameters

These parameters indicate whether the device is currently being used by a TestGrid service.

Parameter	Description
is_run_generator	Device is being used by the Test Case Generator
is_run_build	Device is executing a Scriptless/Codeless test
is_run_local_execution	Device is running local execution
is_run_virtual_usb	Device is being used through Virtual USB
is_run_device_cloud	Device is currently active in a Device Cloud session

Connectivity Status Parameters

Parameter	Description
is_connected	Indicates whether the device is connected to the server
is_offline	Indicates whether the device is offline
is_device_offline	Indicates whether the physical device is unreachable
is_unauthorised	Indicates whether the device requires authorization
is_rebooting	Indicates whether the device is currently rebooting

Reservation Status Parameters

Parameter	Description
is_reserved	Indicates whether the device is currently reserved
reserved_device_user_email	Email address of the user who reserved the device
is_preparing	Indicates whether the device is being prepared for execution
is_cleaning	Indicates whether device cleanup is currently in progress

Status Reference

Device Available

A device is typically available when:

is_connected = 1
is_reserved = 0
is_offline = 0
is_device_offline = 0
is_rebooting = 0

Device Reserved

is_reserved = 1

The device is currently assigned to another user.

Device Offline

is_offline = 1

The device service is offline.

Device Communication Failure

is_device_offline = 1

The device is connected to the server, but communication with the physical device has failed.

Device Unauthorized

is_unauthorised = 1

The device requires authorization before it can be used.

Device Rebooting

is_rebooting = 1

The device is restarting and is temporarily unavailable.

Outcome

The API returns a complete inventory of Android and iOS devices available to the authenticated user, including device metadata, connectivity status, reservation details, execution state information, and automation configuration required for manual and automated testing.