Android or iPhone
What you get
- A cloud phone, usually ready in under a minute (a few minutes with apps at create; an iPhone up to about three), placed in the
us,euorasjurisdiction you ask for.POSTwaits up to about 45 seconds and answers with whatever is true then, usuallycreating; pollGETuntil it isready. - A local network: the phone runs in the US, Germany or Singapore, and its traffic exits through a residential IP in that country, with GPS, timezone, locale and carrier matched to it — so apps see a phone that is where it says it is.
- Nine actions:
screenshot,element_tree,tap(by coordinates or by an element’s text, id or accessibility label),type,press_key,scroll,open_url,launch_app(an installed app by package name, such ascom.android.settings),install_app.press_keynames are Android’s; an iPhone has noBACKorRECENTS, so navigate it with taps andHOME. Most iPhones publish no element tree, soelement_treeand a tap byselectorare400there: tap by coordinates from the screenshot. On an iPhone,open_urlis400(“this device cannot open url”) andlaunch_appis for Android phones (on an iPhone it can wait 30 s and answer409): open links and apps by tapping. An iPhone can show a landscape StandBy screen, at boot and again 15–45 s after you goHOME; a tap does not leave it. The platform opens Settings to leave it when the phone becomes ready and whenever ascreenshotfinds it, so that screenshot shows Settings in portrait. A tap made from an older screenshot can land on StandBy instead: take a fresh screenshot first. - A realtime view of the screen in the dashboard, beside the controls, started on demand.
- Apps from the platform’s app catalogue: many, not all, store apps (Spotify, WhatsApp, Instagram, TikTok and Firefox install; Wikipedia and DuckDuckGo on Android are not offered). There is no list of the catalogue: an app it lacks fails in a second or two,
404at create and400frominstall_app, so try one withinstall_appon a running phone. No upload and no store account: named at create (apps) or installed on the running phone withinstall_app— a package name on Android (com.spotify.music), an App Store bundle id on iOS (com.burbn.instagram). iPhones carry fewer apps than Android phones.
How it ends — timers, not pause
There is no pause. A device lives until you delete it or one of two timers fires, both set at create:
The platform checks every running device once a minute, so a device ends within a minute of its timer.
GET /v1/mobile_devices/{id} also reconciles: it asks the provider and rewrites the stored status when they disagree, filling terminated_at and termination_reason (requested, idle_timeout, max_duration, or unknown when the provider ended it). A fifth reason, unfunded, is the platform stopping a device whose organization can no longer pay for it; see Limits and billing. The list reads stored rows and can lag until a device is opened.
Drive it
tap coordinates, which is what the dashboard’s click-to-tap uses. element_tree lists the named elements on the screen with their bounds in the same pixels, so a tap can name an element instead of a point. An action answers with words; take a screenshot to see its result. install_app waits up to about a minute and answers installed, failed or installing — a large app still going; call it again with the same app to check.
Agents
An agent uses a phone through the built-inmobile tool, on the pi harness only; the other harnesses have no mobile tool. The first call opens a phone for the session, the model sees each screenshot, and the phone shows up in the chat’s Computer panel and on the Mobile page (Computers → Mobile) while the agent works, so you can watch it live. The tool asks for approval by default; approve it for the session once and the agent carries on.
- An agent’s phone takes the tool’s
config:platform(iosfor an iPhone), the same timers, exceptmax_duration_minutesis 1–60 and defaults to 60. The tool waits out an iPhone’s longer boot. open_urlis not bound by the browser’sallowed_domains: a phone opens any URL or deep link. For an agent whose web reach you narrowed, keep the tool onaskor set it todeny.
Live view
The device page’s screen panel has two modes. Screenshot is a picture you click to tap. Live swaps the picture for a realtime stream of the screen, in the same place and at the same size, so the controls beside it stay where they are; Screenshot switches back and drops the stream. The credential behind the stream is a bearer credential — anyone holding it sees and drives the device — so it is held on that screen only, never stored, never logged, never returned inside another object, and withheld from the agent-facing tool catalogue. Each mint is written to the audit log asmobile_device.live_view_opened, without the credential.
In Screenshot mode the page takes a new screenshot after each action, and again when you switch back from Live (the stream can drive the phone too). Taps in Live go straight to the phone, so while it plays the page also takes a screenshot every 30 seconds: that keeps the idle timer from ending a phone you are using. Live is offered once the device is ready; asked for while it is still starting, it answers 409 computer_unavailable.
Limits and billing
- One person or script should drive a device at a time; actions on one device run one after another.
- Apps: up to 10 at create, and any number on a running phone with
install_app, all from the platform’s app catalogue, which carries many but not all store apps (there is no upload route and no catalogue listing). - Capacity: no per-organization limit on live devices. A create is refused with
429 rate_limitedonly when every phone slot on the platform is in use; try again shortly. - Cost: 250 credits per Android phone-minute (15,000 credits an hour) and 400 credits per iPhone-minute (24,000 credits an hour), each including the phone’s residential network, from create to end, rounded up to whole minutes with a one-minute minimum. It is one
mobileline on the ledger, booked once when the device ends. Actions, app installs included, are free beyond the minutes they run in, and a device that fails to provision bills nothing (one still not ready 10 minutes after its create is endedfailed); one that ran and then hit an error is ended and billed for the minutes it ran. The device page shows the rate and the cost so far. See Pricing. - Money: a create is admitted when the balance covers 10 minutes for every live device and the new one, each at its rate (2,500 credits for one Android phone, 4,000 for one iPhone; an agent’s phone included), plus what the live ones have run so far; otherwise it is
402 insufficient_credits, naming the amount needed. Once a minute the platform checks every running device. If the organization’s plan has lapsed, or its balance no longer covers what its running devices have accrued, it ends them withtermination_reason: "unfunded"and bills the minutes they ran. A plan that ispast_duekeeps its devices through the payment grace period. - Phone minutes bill the organization’s balance directly, including a phone an agent opens. They are not held against a session’s or an agent’s budget cap; the timers and the funded-balance check above are what bound them.