Skip to main content
A mobile device is a cloud Android phone or iPhone, the third member of the computer suite beside computers and browser sessions. Seven methods; objects parse with the core MobileDeviceSchema. API detail: Mobile devices.

create

POST /v1/mobile_devices. Every field is optional — an empty body gets an Android 15 phone in the us jurisdiction with a 10-minute idle timeout and a 2-hour ceiling. platform is android or ios, and model is phone. An iPhone has no os_version: omit it (it reads back null; sending one throws validation_failed). An Android phone usually boots in under a minute (a few with apps at create) and an iPhone in up to about three, so the answer is usually creating: poll get until it is ready. jurisdiction (us, eu, as) sets where the phone runs and the country of the residential IP its traffic exits through, with GPS, timezone, locale and carrier to match. There is no limit on how many phones an organization runs, only on the balance: a create needs 10 minutes for every live phone and the new one at their rates (2,500 credits for one Android phone, 4,000 for one iPhone), plus what the live ones have run, or it throws insufficient_credits (402). It throws rate_limited (429) when the platform’s phones are all in use; try again shortly.
apps are installed from the app store when the phone starts: package names on Android, App Store bundle ids on iOS.

list

GET /v1/mobile_devices, cursor-paginated, terminated devices excluded; session_id narrows it to the phone that agent session opened. Reads rows only; see get for the reconciled read.

get

GET /v1/mobile_devices/{id}. Asks the provider and rewrites the row when they disagree — the read that notices an idle-timer termination.

update

PATCH /v1/mobile_devices/{id}. The name, and nothing else.

act

POST /v1/mobile_devices/{id}/act. One action; the device must be ready. image is { content_type: "image/jpeg", data: "<base64>" } on a screenshot, at half the screen’s resolution on Android and full resolution on an iPhone; its pixels map 1:1 to tap coordinates. Every other action answers image: null, so take a screenshot to see its result. press_key takes Android’s key names; an iPhone has no BACK or RECENTS, so navigate it with taps and HOME. install_app installs an app from the app store onto the running phone (a package name or bundle id, as in apps). Its output is a MobileInstallAppOutput, { app, status, error }: installed, failed with an error, or installing when a large app outlasts the call’s minute — act again with the same app to check on it.

liveView

POST /v1/mobile_devices/{id}/live_view. Answers url, the device’s page on the dashboard, where the screen plays live. stream (a wss:// address and token for the dashboard’s player) is returned only to a signed-in member, so with an API key it is null: open url. Needs computers:write; a device still starting answers computer_unavailable, and one that has ended answers not_found. stream is a bearer credential — whoever holds it drives the device until it ends. Do not log or store it; play it and let it die with the device. expires_at is null. Each mint is audited as mobile_device.live_view_opened, without the credential.

delete

DELETE /v1/mobile_devices/{id}. Ends the device; idempotent.