# 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`

```json
// 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

```json
// 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`

```json
// 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`

```json
// 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`

```json
// 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.

```json
// 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.

```json
// 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.

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

* Parameter Details

| Parameter | Type   | Required | Description            |
| --------- | ------ | -------- | ---------------------- |
| id        | string | Yes      | Cloud phone profile ID |

```json
// 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.

```json
// 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.

```json
// 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.

```json
// 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.

```json
// 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.

```json
// 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.

```json
// 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.

```json
// 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.

```json
// 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.

```json
// 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.

```json
// 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`

```json
// 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`

```json
// 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`

```json
// 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`

```json
// 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.

```json
// 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.

```json
// 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.

```json
// 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         |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.bitbrowser.net/api-docs/cloud-phone-profiles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.