Cloud Phone Profiles

API Documentation

1. The concurrency limit for cloud phone APIs is different from browser windows. The limit for cloud phone API requests is: 1 request per second.

2. Many cloud phone APIs involve billing, especially for actions like powering on, suspending, and shutting down. Please make sure to understand the details thoroughly before performing these operations.

3. Operations related to cloud phone management, such as powering on, shutting down, performing a one-click fresh start, installing, and uninstalling apps, are asynchronous APIs. They do not immediately return the cloud phone’s status. After calling these APIs, you need to call the check power-on status API to verify if the cloud phone has powered on.

4. When using temporary computing power, billing starts immediately after the cloud phone is powered on and stops when the cloud phone is powered off. Please be sure to understand this.

Create Cloud Phone Profile

POST /phone/profile/add

// Example of request body
{
  "computeType": 0,
  "name": "",
  "remark": "",
  "port": 45001,
  "proxyUserName": "xge66fa14336ca14",
  "proxyPassword": "dMpfTa0tbr512cmi4P",
  "host": "1.2.3.4",
  "regionId": "d69bcf13db844d1cb81e779f64161223",
  "cloudPhonesFingerPrint": {},
  "ipCheckService": "ip123in",
  "udp": 1
}

• Parameter Details

Parameter	Type	Required	默认值	Description
regionId	string	Yes	-	Compute type ID, click the "ADD" button in the client interface, select the type, then click the copy button on the right to copy the ID.
computeType	int	Yes	0	Compute type, options: 0, 1, 2; (0: Smart Allocation, 1: Temporary Compute Power, 2: Monthly Compute Power)
name	string	No	-	Profile name, maximum 30 characters
remark	string	No	-	Profile remark, maximum 500 characters 符
host	string	Yes	-	Proxy host, e.g., 1.2.3.44
port	int	Yes	-	Proxy port, e.g., 123
proxyUserName	string	Yes	-	Proxy username, maximum 200 characters
proxyPassword	string	Yes	-	Proxy password, maximum 200 characters
ipCheckService	string	Yes	ip123in	Proxy IP check service, options: ip123in, ip-api
udp	int	Yes	1	Proxy UDP protocol, options: 1, 0; If unable to connect to the network, you may try turning off UDP (not recommended to turn off)
cloudPhonesFingerPrint	object	Yes	{}	Fingerprint configuration object, defaults to no configuration unless there is a special requirement. If control is needed, refer to the JSON object below.

• cloudPhonesFingerPrint object

// Example of request body
{
  "isIpCreatePosition": true, // Generate geographic location based on IP; if not enabled, can be customized.
  "isIpCreateLanguage": true, // Generate corresponding system language based on IP country.
  "isIpCreateTimeZone": true, // Generate corresponding time zone based on IP.
  "timeZone": "", // Custom time zone when isIpCreateTimeZone is false.
  "timeZoneOffset": 0, // Custom time zone offset when isIpCreateTimeZone is false.
  "localeLanguage": "", // Custom language when isIpCreateLanguage is false.
  "longitude": "", // Custom longitude when isIpCreatePosition is false.
  "latitude": "" // Custom latitude when isIpCreatePosition is false.
}

Modify Cloud Phone Profile, RegionId (Compute Type) Cannot Be Modified

POST /phone/profile/update

// Example of request body
{
  "id": "2c9cce4493a98fa90193aa7d71e70043",
  "name": "Modified Name"
}

• Parameter Details

Except for the ID, only the fields that need to be modified should be passed. For example, if the name needs to be modified, only the ID and name fields need to be passed. The full request parameters are the same as those of the /phone/profile/add endpoint.

Open Cloud Phone

Opening a cloud phone is an asynchronous API. If the cloud phone is in a powered-off state, it typically takes around 1 minute to power on. If the cloud phone is being resumed from a suspended state, it can take as little as 5 seconds to open. During this time, you can call the /phone/running API to check if the cloud phone has powered on.

POST /phone/openphone

// Example of request body
{
  "id": "2c9cce44930a5b0e01930a7c95b0000a"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID

Get Cloud Phone Profile List

POST /phone/list

// Example of request body
{
  "page": 0,
  "pageSize": 2
}
// In the returned list, if adb is enabled in the environment, the adb connection information will be returned in the list, as follows:：
// "{\"code\":\"SAjp7zSIJfHGAZi9Ot\",\"port\":21136,\"ip\":\"124.236.71.153\"}"
// Please format it yourself, code is the adb connection password

• Parameter Details

Parameter	Type	Required	Description
page	number	Yes	Page number, starting from 0
pageSize	number	Yes	Number of items per page, maximum 100. If a number greater than 100 is passed, only 100 items will be returned
groupId	string	No	Group ID ID
name	string	No	Profile name, fuzzy matching
seq	number	No	Sequence number, exact match
minSeq	number	No	Minimum sequence, query data greater than this sequence number
maxSeq	integer	No	Maximum sequence, query data less than this sequence number
host	string	No	Proxy Host, exact match

Suspend Cloud Phone

POST /phone/suspend

Closes the phone window and suspends the phone. The phone will continue running on the cloud and continue to be billed.

// Example of request body
{
  "id": "2c9cce4493a98fa90193aa7d71e70043"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID

Shutdown Cloud Phone

POST /phone/shutdown

Closes the cloud phone window and shuts down the phone. The phone will no longer run on the cloud and billing will stop.

// Example of request body
{
  "id": "2c9cce4493a98fa90193aa7d71e70043"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID

Get the cloud phone’s boot status

POST: /phone/running

Check if the cloud phone is powered on.

// Example of request body
{
  "id": "2c9cce4493a98fa90193aa7d71e70043"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID

// Example of response body
{
  "success": true,
  "data": true // true: Enable root access, false: Disable root access
}

Enable/Disable Cloud Phone Root Access

POST /phone/root/switch

Switching root access is an asynchronous operation, and it is not possible to directly check if root has been successfully enabled or disabled. Users must use third-party tools to monitor the status. Root access can only be toggled when the cloud phone is in a powered-on state.

// Example of response body
{
  "id": "2c9cce4493a98fa90193aa7d71e70043",
  "enable": true
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID
enable	boolean	Yes	true: Enable root access, false: Disable root access

Upload File

POST /phone/uploadFile

When uploading files, if multiple profiles are uploading the same file, it is best to pass the list of profile IDs that need the file upload in one request. The server will upload the local file once and then distribute it to the specified profiles.

The file upload must wait for the previous upload to finish before continuing.

// Example of request body
{
  "path": "C:\\Users\\admin\\AppData\\Roaming\\logs\\aaa.log",
  "ids": ["2c9cce4493a98fa90193aa7d71e70043"]
}

• Parameter Details

Parameter	Type	Required	Description
path	string	Yes	Absolute file path, e.g., "C:\Users\admin\xxx\aa.txt"
ids	array	Yes	Cloud phone profile ID array

Clear App Data

POST /phone/clearAppData

Clears the app’s cache data. The user login status will be cleared. Use with caution.

// Example of request body
{
  "id": "2c9cce4493a98fa90193aa7d71e70043",
  "packageName": "com.google.android.googlequicksearchbox"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	profile ID
packageName	string	Yes	App package name

Recover Phone Profile

POST /phone/profile/recover

Resets the cloud phone profile parameters. Each profile can perform a maximum of 60 fresh starts per month. Once used up, the quota resets the next month. Use with caution.

// Example of request body
{
  "id": "2c9cce44930a5b0e01930a7c95b0000a"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID

Install App

POST /phone/installApp

Installs an app from the app store. Copy the corresponding version app ID from the app store and call this API to install the app.

// Example of request body
{
  "id": "2c9cce44930a5b0e01930a7c95b0000a",
  "appId": "1855178384240701441"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID
appId	string	Yes	App ID from the app store

Uninstall App

POST /phone/unInstallApp

Uninstalls the specified app from the cloud phone.

// Example of request body
{
  "id": "2c9cce44930a5b0e01930a7c95b0000a",
  "packageName": "com.example.app"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID
packageName	string	Yes	App package name

Launch App

POST /phone/launchApp

Launch the specified app by package name.

// Example of request body
{
  "id": "2c9cce44930a5b0e01930a7c95b0000a",
  "packageName": "com.xxx.xxx"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID
packageName	string	Yes	App package name

Close App

POST /phone/closeApp

Closes the app, but the app will continue running in the background.

// Example of request body
{
  "packageName": "com.xxx.xxx",
  "id": "2c9cce44930a5b0e01930a7c95b0000a"
}

• Parameter Details

Parameter	Type	Required	Description
packageName	string	Yes	App package name
id	string	Yes	Cloud phone profile ID

Restart Cloud Phone

POST /phone/restart

Restarts the cloud phone. During the restart, no cloud phone features can be used.

// Example of request body
{
  "id": "2c9cce44930a5b0e01930a7c95b0000a"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID

Get List of Installed Apps on Cloud Phone

POST /phone/getInstalledAppList

Gets the list of installed apps on the cloud phone. Only user-installed apps can be retrieved; system apps cannot be accessed.

// Example of request body
{
  "id": "string"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Cloud phone profile ID

Get Cloud Phone Group List

POST /phone/group/list

// Example of request body
{
  "page": 0,
  "pageSize": 4,
  "all": true
}

• Parameter Details

Parameter	Type	Required	Description
page	number	Yes	Pagination, starting from 0
pageSize	number	Yes	Number of items per page, max 100, default is 10
all	boolean	No	By default, only retrieves the current user’s groups. To retrieve groups within the user’s permissions, pass true.

Add Group

POST /phone/group/add

// Example of request body
{
  "groupName": "111",
  "sortNum": 3
}

• Parameter Details

Parameter	Type	Required	Description
groupName	string	Yes	Group name
sortNum	number	Yes	Sorting order

Edit Group

POST /phone/group/edit

// Example of request body
{
  "id": "2c9cce4492b877120192b87811650009",
  "groupName": "11",
  "sortNum": 3
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Group ID
groupName	string	Yes	Group name
sortNum	number	Yes	Group sort order

Delete Group

POST /phone/group/delete

// Example of request body
{
  "id": "2c9cce44932f0e8401932f388bdd0015"
}

• Parameter Details

Parameter	Type	Required	Description
id	string	Yes	Group ID

Batch Update Remarks

POST /phone/batchUpdate/remark

Batch update remarks. Supports replacement or append mode. By default, the mode is replacement. In append mode, the provided data will be appended to the existing remarks.

// Example of request body
{
  "phoneIds": ["2c9cce44931abdda01931e5354ba0168", "2c9cce44930a5b0e01930a7c95b0000a"],
  "remark": "12"
}

• Parameter Details

Parameter	Type	Required	Description
phoneIds	array	Yes	List of Cloud phone profile IDs
remark	string	Yes	Remark text
remarkType	integer	Yes	Optional values: 1 (replace), 2 (append), default is 1

Batch Update Groups

POST /phone/batchUpdate/group

Batch update profiles to the same group.

// Example of request body
{
  "groupId": "2c9cce4492b877120192b87811650009",
  "phoneIds": ["2c9cce4492be13790192be16f965000a", "2c9cce4493007978019300809a9d0007", "2c9cce44931abdda01931e5354ba0168"]
}

• Parameter Details

Parameter	Type	Required	Description
groupId	string	Yes	Group ID
phoneIds	array	Yes	List of Cloud phone profile IDs

Batch Update Proxies

POST /phone/batchUpdate

Batch update proxy settings for profiles to the same specified proxy information.

// Example of request body
{
  "phoneIds": ["2c9cce4492be13790192be16f965000a", "2c9cce4493007978019300809a9d0007", "2c9cce44931abdda01931e5354ba0168"],
  "host": "1.2.3.4",
  "port": "59059",
  "proxyUserName": "ImL5bo00",
  "proxyPassword": "JYZG7Eqj"
}

• Parameter Details

Parameter	Type	Required	Description
phoneIds	array	Yes	Cloud phone profile ID
host	string	Yes	Proxy host
port	int	Yes	Proxy port
proxyUserName	string	Yes	Proxy username
proxyPassword	string	Yes	Proxy password