Skip to main content

Cloud Phones API

Use your existing API key to create profiles in paid slots, launch phones, open their private viewer and configure root and ADB (Android Debug Bridge, a connection for controlling Android). These operations use the same billing, ownership and device checks as the dashboard.

Swagger: cloud-phones describes the live schema. From API Access, open Swagger or API Docs. In Swagger, choose Authorize → ApiKeyAuth and enter your key; requests use X-Api-Key.

Before you start​

You need an active account, an API key from API Keys, a free paid profile slot, an active paid period, a positive minutes balance and a usable proxy. Creating a profile reserves an existing slot; it does not buy slots or launch a phone. Launching a phone consumes paid minutes. Root also depends on provider/device support; ADB enabling supports Android 11–15.

export BASE_URL='https://app.cyberyozh.com'
export API_KEY='replace-with-your-api-key'

Never put the API key into a URL. Every API request below needs X-Api-Key; browser opening uses the normal signed-in account instead. Keys, proxy passwords and ADB passwords are private.

MethodPath after /api/v2/cloud-phones/profiles/Purpose
GET(collection)List your profiles
POST(collection)Create in a free paid slot
GET{id}/Read profile and launch result
POST{id}/start/Request launch
POST{id}/adb/Enable/disable ADB
GET{id}/adb/Read ADB connection details
POST{id}/root/Enable/disable root

There are seven operations. Slot purchases, stop, delete, clone, applications and GPS are not exposed by this public API.

1. List your profiles​

curl "${BASE_URL}/api/v2/cloud-phones/profiles/" \
-H "X-Api-Key: ${API_KEY}"

HTTP 200 example with no profiles:

{"count":0,"next":null,"previous":null,"currentPage":1,"nextPage":null,"prevPage":null,"results":[]}

The response is paginated: count, next, previous, currentPage, nextPage, prevPage, results. Query parameters include page, page_size, search, status and group (your group's UUID). For example, ?status=running&page_size=10. Only your non-deleted profiles appear. Missing, invalid, revoked or expired keys return 403, even if a browser session exists. A request for another owner's profile returns 404 without its data or link.

2. Create a profile​

curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/" \
-H "X-Api-Key: ${API_KEY}" \
-H 'Content-Type: application/json' \
-d '{"name":"Automation phone","proxy":{"proxy_information":"socks5://example-user:example-password@203.0.113.10:1080"},"device":{"android_version":"13","region":"sgp"}}'

Replace the example proxy with an actual usable proxy. name is required; note, device settings and proxy settings are optional. You can save a profile without a proxy, but cannot launch it until one is configured. Device region is cn, sgp or us; us requires Android 15. The default Android version is 13. For all supported create fields and proxy modes, use Swagger.

HTTP 201 example:

{
"id": "11111111-1111-4111-8111-111111111111",
"name": "Automation phone",
"note": "",
"status": "slot_reserved",
"is_viewable": false,
"view_url": null,
"runtime": {
"elapsed_seconds": null,
"confirmed_seconds": 0,
"current_started_at": null,
"as_of": null,
"accuracy": "unknown",
"reason": "legacy_history"
},
"android_version": "13",
"device_model": null,
"proxy_source": "manual",
"proxy": {
"source": "manual",
"configured": true,
"is_expired": false,
"scheme": "socks5",
"host": "203.0.113.10",
"port": 1080,
"user_proxy_ref": null,
"rotating_sub_user_id": null,
"rotating": null,
"manual_information": "socks5://example-user:example-password@203.0.113.10:1080"
},
"groups": [],
"is_root_enabled": false,
"is_adb_enabled": false,
"created_at": "2026-11-10T05:00:00Z",
"last_started_at": null,
"last_start_error": null
}

Save the actual id returned by your request:

export PROFILE_ID='replace-with-created-profile-id'

slot_reserved means the profile has a slot and the phone has not been provisioned or started. Without a free slot you get 402 with code: "no_free_slots". A scheduled reduction in slot capacity can return 409 with code: "profiles_pending_limit".

3. Launch and poll​

curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/start/" \
-H "X-Api-Key: ${API_KEY}"

No request body. HTTP 200 returns the full profile, usually with status: "starting" and view_url: null. Launching is asynchronous; repeated start requests while starting or running do not send another launch.

Poll the detail endpoint, with a delay between requests and an overall deadline:

curl "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/" \
-H "X-Api-Key: ${API_KEY}"

HTTP 200 returns the full profile. Wait until view_url is non-null; stop polling if last_start_error is non-null. Selected fields from a ready profile:

{
"id": "11111111-1111-4111-8111-111111111111",
"status": "running",
"is_viewable": true,
"view_url": "https://app.cyberyozh.com/my-account/cloud-phones/view/11111111-1111-4111-8111-111111111111/",
"last_start_error": null
}

A failed launch is visible in the profile even if the start request originally returned 200. Example fields:

{
"status": "stopped",
"view_url": null,
"last_start_error": {
"code": "provider_start_failed",
"detail": "The phone did not start: the cloud phone service refused to start it. Try again later.",
"failed_at": "2026-11-10T05:01:00Z"
}
}

4. Open the phone​

Open the returned view_url in your browser. This is the same owner link as the phone card, using the configured main app origin and the default English route regardless of Accept-Language. It contains neither an API key nor a bearer viewer token. A guest goes through normal sign-in and returns to the requested phone; another account cannot read the profile or obtain its viewer session.

The same ready profile has the same link in list and detail responses. view_url is a read-only nullable URI: it is null for reserved, stopped, starting or failed phones and when a valid viewer session for the current run is missing. running alone is insufficient. A restart must become ready again. The existing is_viewable field can be true during starting; use view_url to decide whether this public API is ready to open.

This is not a guest/share link. Keeping a URL does not keep a phone running or bypass subsequent access/state checks.

5. Enable ADB and get connection details​

The phone must be running. Enabling ADB requires Android 11–15; unsupported versions return 422. The flag changes only after provider confirmation.

curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/adb/" \
-H "X-Api-Key: ${API_KEY}" -H 'Content-Type: application/json' \
-d '{"enabled":true}'

HTTP 200 returns the full profile with is_adb_enabled: true. This does not mean the connection is ready yet. Poll with a delay and deadline:

curl "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/adb/" \
-H "X-Api-Key: ${API_KEY}"

HTTP 200 example (all four values are strings):

{
"ip": "203.0.113.20",
"port": "5555",
"password": "example-adb-password",
"connect_command": "adb connect 203.0.113.20:5555"
}

Use the returned connect_command, together with the connection password when requested. 409 means ADB is preparing or the phone is not running: check the profile before retrying. 422 means ADB is disabled or unavailable on that device; waiting alone does not fix it. To disable, POST {"enabled":false}. GET and HEAD do not change the ADB flag.

6. Enable root​

Root means privileged Android access. It requires a running phone and provider support for that device.

curl -X POST "${BASE_URL}/api/v2/cloud-phones/profiles/${PROFILE_ID}/root/" \
-H "X-Api-Key: ${API_KEY}" -H 'Content-Type: application/json' \
-d '{"enabled":true}'

HTTP 200 returns the full profile with is_root_enabled: true, saved after provider confirmation. A following GET profile shows both flags enabled if you enabled both functions successfully. A stopped phone returns 409; provider refusal returns 502 and does not change the flag. To disable root, POST {"enabled":false}.

Errors and limits​

HTTPMeaning / action
400Invalid field, device/proxy settings or expired proxy
402No free paid slot, expired paid period or no minutes
403API key missing, invalid, revoked or expired
404Profile missing, deleted, foreign or invalid UUID
405Method not exposed on that path
409State conflict, ADB preparing or scheduled capacity limit
422ADB disabled/unavailable or device cannot support the action
429Request limit exceeded; respect Retry-After
502/503Provider refusal or temporary unavailability

Domain errors use detail and may include code, for example:

{"detail":"No free profile slots.","code":"no_free_slots"}

Other paid-access codes include period_expired and no_minutes. Validation can return field-keyed messages instead:

{"name":["This field is required."]}

Do not assume every error has detail/code; use HTTP status and a code when present. Messages can be localized.

Read/list/create: 50 requests per second per user; start: 20; root and ADB: 5. Budgets are shared with corresponding dashboard operations and other keys of the same user. Bound retries and polling; honor Retry-After.