Skip to main content
This is the shortest complete thing you can do with PhoneUse: get a device and make it do something. Everything below was run end to end with a real card on a real device. The numbers are readings, not illustrations, except where a block says it is an example.
What it costs. One cloud phone, billed monthly at the rate published on Billing modes: Cloud phone from $20 a month, Real phone identity $39 a month. Payments are not refunded: a Cloud phone keeps its paid period, and you stop the next charge with Cancel order on the Billing page. To rent by the minute instead, see Billing modes.What you need. A browser, an org admin sign in, and a card. Nothing installed. About fifteen minutes.What you do not need. An API key, unless you want to do step 3.

Step 1: Buy a device

Go to Add a phone (/devices/add). The screen draws itself from GET /v1/skus, which is the deployment’s actual price list. One entry per pair of thing and billing mode, and each Cloud phone model carries its own price and quoteId. A model whose price could not be read just now is still listed, but without price or quoteId, and it cannot be bought until a later read shows both; a purchase screen should offer a model only when it has both. An abridged example, not a reading:
Three things to read off that. amountMinor is the minor unit: 2000 with currency: "usd" means twenty dollars, not two thousand. Cloud phone prices include tax: any tax is inside the amount, not added on top. They come from the payment provider’s own price objects, carried through unaltered; this service does no arithmetic on a charge. The current rate card is on Billing modes, and phoneuse.com is canonical if the two disagree. A pair this deployment holds no price for is absent from the list rather than shown without a number. So the list is exactly what can be bought here today, and a card you cannot see is not a card you are missing. stock says whether a free unit of that kind exists right now, and it has three answers: shipsNow is the older field for the same answer: true exactly when stock is in_stock, so it cannot tell out_of_stock from unknown.
On the hosted service, a model that is sold out in the region you chose is refused with 409 out_of_stock before any payment, so you are never charged for a phone that cannot be set up. Pick another model or region, or try again later. stock is a verdict, never a count: how much stock is left is not published.
Press the buy button and the console starts a checkout with POST /v1/checkout-sessions, which hands back somewhere to send the browser:
The checkout is hosted by the payment provider. Promotion codes are accepted on it, so a code you were given goes in there rather than anywhere in this product. Pay, and the order settles on its own. You do not have to do anything to claim the device: the payment provider tells the control plane, your phone is prepared only after your payment and set up for you, and the device then appears in GET /v1/devices and on /devices. If you would rather be told than poll, the fulfilment.changed webhook is the event for exactly this.
Buying needs an org admin, signed in, or an API key that holds orders:place. Only an admin can mint or approve such a key, and a person still pays on the Checkout page, so a program cannot spend money while nobody is watching. A member, and a key without that scope, answer 403. An org can buy as many phones as it needs; there is no “already subscribed” refusal. Send an Idempotency-Key header and a retried checkout gets the first answer back instead of opening a second one.

Step 2: Drive it from the console

Open /devices/:id for the device that appeared.
  1. Click the screen. The picture is the tap target. The console turns where you clicked into a coordinate on the normalized grid and sends the tap. Your first tap takes a lease on the device for ten minutes if your org holds none; if an agent’s run already holds one, your tap runs under it and the run keeps going.
  2. Keep clicking. A lease you took yourself stays alive while you drive.
  3. Release the lease when you are done, or let it expire.
Read a disabled control as information rather than as breakage. A control the device cannot perform is drawn disabled and says Action not supported on this device. That is its capabilities block speaking. A cloud phone reports tap, swipe, typeText: "native", openApp: "intent", installApp: "managed_store" and every key in pressKey, and it has no element tree (uiTree: false). installApp: "managed_store" means apps are installed from the Apps page in the Console, not by sending a package to the phone. Release the lease before you wander off. Nothing pauses the clock while a lease is held, and nothing watches for idleness. A lease expires ten minutes after it was granted and can be renewed, and no lease lives longer than sixty minutes from when it was acquired, so the worst case is bounded but it is not free.

Step 3: Drive it from the API

Everything the console just did is three routes. Mint an API key at /keys with three of the eight scopes: devices:read to see it, devices:lease to take it, devices:act to touch it. Keys are for servers: an API key sent from a browser origin is refused with api_key_from_browser_origin whatever its scopes are.

Take the device

201, and the request takes no body at all. Keep the leaseId (export LEASE=...): it is a credential, it is returned by this call and by no other, and every gesture and the release need it. A refusal does not say why, and that is deliberate. Somebody else holding the device, a spent quota and an unreachable device all answer the same way.

Look at the screen

200, image/jpeg. The measured run returned a 720 by 1280 frame of 52428 bytes. You do not need the lease for this one. Any credential in the org that can see the device can watch it, whoever is holding it, which is the point: a person should be able to see what a device is doing before deciding whether to interrupt it. Watching writes no receipt and returns no frameId. If you intend to bind an action to the exact frame you decided on, take the screenshot through the MCP screenshot tool instead, which issues one. See Reading a trace.

Act

200. status has exactly one value: an action that did not commit is an error, not a different status. The response resolves only once the device applied the gesture, which is why it is not instant. One tap measured today took 5076 ms from request to committed. Six gestures are available on this route, discriminated by action: press_key takes one of home, back, enter, delete, app_switch, power, volume_up, volume_down. Any of them can still be refused by a device that declared pressKey: false, which is the whole reason to read capabilities first rather than to assume a set. Every attempt is written to the receipt ledger before it is dispatched, so GET /v1/receipts can tell you what happened even if you lost this response. Send your own idempotencyKey and a retry replays that outcome instead of touching the phone twice. On this route it is a field in the body, not a header. (Checkout and some other routes take an Idempotency-Key header instead.) When you do not send one the service generates it and returns it, which is why the response above carries one you never chose.

Give it back

The lease id goes in the body of a DELETE, which is unusual and deliberate: the id is a credential, and a query string is written to access logs, browser history and Referer headers. Releasing a device you do not hold does nothing, so a retry is safe. Working longer than ten minutes? PATCH /v1/devices/{deviceId}/lease with the same leaseId slides the expiry to ten minutes from now. It does not add ten minutes to the old one, and the leaseId does not change. Renew before it expires: an expired lease cannot be renewed, because by then the device belongs to whoever takes it next.

When you are done with a device

Devices are not returned online. A Cloud phone keeps its paid period: stop the next charge with Cancel order on the console’s Billing page (POST /v1/fulfilments/{id}/cancel-renewal) and it stays yours until the paid period ends. For any other device, or a question about an order or a payment, contact support at abdulla@phoneuse.com and we’ll help. POST /v1/fulfilments/{id}/return and POST /v1/fulfilments/{id}/cancel both answer 409 wrong_state with that support address, and nothing is changed or refunded.
Robot hand + iPhone: buy it in the console. In Add a phone, choose Robot hand + iPhone and pay $149 a month per robot at checkout. We prepare it within 24 hours after payment. It is not part of the API, MCP or CLI today.

What you were charged

  • The device, every 30 days, at the published rate. The first charge covers a slightly shorter first period (about 28 days), so that every later charge lands two days before the phone’s 30-day term ends. Payments are not refunded.
  • Active time is not a separate line on a monthly device. A monthly device has no meter: run it all the time and the invoice reads the same. Per minute phones are the other way to pay, from a prepaid balance. See Billing modes.
  • Agent steps are metered but not separately priced. Steps are included in the device price today, and no separate step rate is published.
There is no dollar limit you can set. The limits that actually stop something are a per minute phone’s prepaid balance, the lease expiry and a run’s own step budget. See Spending controls.

Where to go next

Webhooks

Be told when a run ends instead of polling for it.

Agent tier

Hand a goal to a worker instead of driving each step yourself.

The console

Every screen, and the surfaces that have no screen.