Cloud phone API for AI agents
Real Android 14 phones in the cloud. Install any APK, give an AI agent a goal in plain words or drive the screen yourself. Paid per awake hour.
Last updated 2026-11-05
Black Friday deposit bonus
Every qualifying top-up earns free credit, on top of any other offer.
Ends November 30
Some apps have no API: the only way in is the screen. A cloud phone is a real Android 14 phone that runs in the cloud and that your code controls over /v1/phones. Install the app from an APK, then hand the phone to our phone agent with a goal in plain words, or tap, type and swipe from your own code. A person can watch the screen live, or take it over, from any browser. A phone costs $1.20 per hour while it is awake, billed per minute, and nothing while it sleeps.
Hand it to your AI agent
Copy this prompt into Claude Code, Cursor, Codex or any coding agent. It tells the agent where the docs are and how to use your API key.
Run an Android task for me on a Lovely Router cloud phone: create a phone, install the app I name, and let the phone agent do the goal, or drive it step by step. - Docs (read first): https://lovelyrouter.com/docs/phone.md and https://lovelyrouter.com/docs/api/phones.md - Phones: POST https://lovelyrouter.com/v1/phones creates one; install apps from an https URL or an uploaded APK; start an agent run with a plain-language goal and poll it; answer its questions at the run's reply endpoint. - Billed per awake minute while the phone is awake (asleep is free); delete the phone when you are done. - Auth: read my API key from the LOVELY_API_KEY environment variable and send it as `Authorization: Bearer $LOVELY_API_KEY`. Never print or commit the key. If it is not set, ask me to create one at https://lovelyrouter.com/app/keys. - Billing is prepaid: every call is charged to my balance, so test with a small request before running anything large. - Every docs page is plain Markdown; the full index is https://lovelyrouter.com/llms.txt. My task: <the app, the goal on the phone and what proves it worked>
Two ways to work a phone
| Phone agent | Direct control | |
|---|---|---|
| You send | A goal: "Open the app, search for Termux and tell me the first result" | Taps, swipes, typing and key presses, one action at a time |
| Who decides each step | Our agent reads the screen and acts until the goal is done | Your code or your own agent |
| You get back | An answer, plus the steps with trace=1 | {"ok": true}, and the screen after the action if you ask |
| Extra cost | The chat model's tokens at their normal API price | None beyond the phone |
Both use the same phone, so you can mix them: let the agent log in, then take screenshots and drive the rest yourself.
Run a goal on a new phone
Start the run
POST /v1/phones/runscreates a phone, installs the apps you list and starts the agent. It answers at once with202, the run'sidand itsphone_id. A new phone takes about a minute to start, longer while it installs apps.cURLcurl https://lovelyrouter.com/v1/phones/runs \ -H "Authorization: Bearer $LOVELY_API_KEY" \ -H "content-type: application/json" \ -d '{ "goal": "Open the F-Droid app, search for Termux, and tell me the one-line summary of the first result.", "apps": ["https://f-droid.org/F-Droid.apk"] }'Wait for the answer
GET /v1/phones/runs/{id}?wait=50holds the request for up to 50 seconds and answers early when the run ends or asks you something.Pythonimport os, requests API = "https://lovelyrouter.com/v1/phones" H = {"Authorization": f"Bearer {os.environ['LOVELY_API_KEY']}"} run = requests.post(f"{API}/runs", headers=H, json={ "goal": "Open the F-Droid app, search for Termux, and tell me the one-line summary of the first result.", "apps": ["https://f-droid.org/F-Droid.apk"], }).json() while run["status"] in ("queued", "running"): run = requests.get(f"{API}/runs/{run['id']}", headers=H, params={"wait": 50}).json() print(run["status"], run["answer"])Keep the phone
The phone stays yours after the run, with its apps and logins. Send the next goal to it with
POST /v1/phones/{phone_id}/runs.Node.jsconst H = { Authorization: `Bearer ${process.env.LOVELY_API_KEY}`, 'content-type': 'application/json' }; const next = await (await fetch(`https://lovelyrouter.com/v1/phones/${phoneId}/runs`, { method: 'POST', headers: H, body: JSON.stringify({ goal: 'Open F-Droid and list the first three apps under Latest.', wait: 50 }), })).json(); console.log(next.status, next.answer);
The phone agent
The agent reads what is on screen, taps, types and scrolls until the goal is done. Write the goal with every value the task needs, up to 10,000 characters. Each run takes up to 200 steps (max_steps, 40 by default) and uses any chat model from the model list as model; the default is gemini-3.8-flash.
(the default): the chat model decides every step, a few seconds each. Use it for goals that need judgement.
("mode": "fast"): a fast decision model picks most steps in well under a second from the screen's elements and the screenshot, so it can also tap things that aren't buttons, such as game pieces and pictures, and swipe. A coach model writes a short strategy beside it and rewrites it every few steps or when the run looks stuck. Both are included in the phone's price; the chat model only writes the final answer, so a fast run also uses fewer tokens. Fast mode suits games, dismissing dialogs and tapping through a known flow.
If the agent needs a code sent by text message, a password or a decision, the run turns waiting with a question. Answer with POST /v1/phones/runs/{id}/reply, or do the step yourself on the live screen and reply done.
The agent never pays, sends money, deletes data or posts publicly unless the goal says so. POST /v1/phones/runs/{id}/stop ends a run after its current step.
Any app, from an APK
The phone has Chrome, Settings and the standard Android apps, plus Google Play services, but no Play Store. Apps come from APK files: any .apk, and split bundles as .apks or .xapk, whose game data (OBB files) is copied to the phone too.
- By URL: list up to 20
https://links inappswhen you create the phone, or install one later withPOST /v1/phones/{id}/apps. - By upload: store your own APK once with
PUT /v1/phones/apks/{name}(up to 100 MB in one request) and install it by name on any phone. Files up to 500 MB go up in 50 MB parts that can be sent in any order or at the same time.
curl -X PUT https://lovelyrouter.com/v1/phones/apks/myapp.apk \
-H "Authorization: Bearer $LOVELY_API_KEY" \
--data-binary @myapp.apk
curl https://lovelyrouter.com/v1/phones/ph_2758eedebf08496f87e0/apps \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{"apk": "myapp.apk"}'Drive the screen yourself
Your own code, or an agent you built, can work the phone directly. Coordinates are pixels of the screenshot, whose short side is 540 pixels.
GET /v1/phones/{id}/screenshotreturns the screen as WebP.GET /v1/phones/{id}/elementslists the buttons, text and fields on screen, each with its center point, size and flags such asclickableandeditable.POST /v1/phones/{id}/actionssendstap,long_press,swipe,scroll,type(any language),key,open_url,launch,stop_app,wait,rotateorshell. Add"screenshot": trueto see the result.
curl https://lovelyrouter.com/v1/phones/ph_2758eedebf08496f87e0/actions \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{"action": "type", "text": "weather Tokyo", "submit": true, "screenshot": true}'Live screen, portrait or landscape
POST /v1/phones/{id}/screen returns a link to the phone's live screen. It opens in any browser without a plugin and can sit in an iframe on your own page, so your user can watch an agent work or finish a login by hand. Anyone with the link can tap and type, so share it only with the person meant to use the phone; it lasts an hour by default and up to 24 hours. When an app turns to landscape, or you send rotate, the screenshot becomes 1200×540 and the live screen turns with it. In the browser, the phone console does all of this without code.
What you pay
| Price | |
|---|---|
| A phone while it is awake | $1.20 per hour, billed per minute |
| A phone while it is asleep | Free |
| Agent runs | The chat model's tokens at the normal API price; fast mode's decision and coach models are included |
| Uploaded APKs | The first 1 GB free, then $0.30 per GB a month, billed hourly |
A phone falls asleep after 5 minutes without use and wakes in about 2 seconds, with the screen as you left it. A phone that hasn't been used for 1 hour is deleted with its apps and data, or delete it yourself with DELETE /v1/phones/{id}. Starting a phone needs 15 minutes of phone time on your balance; when the balance runs out, runs stop and the phone falls asleep. Phones use the same prepaid key as your model calls, data tools and cloud agents; there is no subscription.
Frequently asked questions
What is a cloud phone?+
An Android 14 phone that runs in the cloud instead of in your hand. It runs real Android apps, and your code reaches it over an API: screenshots, the elements on screen, actions, app installs and a live screen link.
Can I install apps from the Play Store?+
No. The phone has Google Play services but no Play Store, so you install apps from APK files: by https:// link, or by uploading the file once and installing it by name. Split bundles (.apks, .xapk) work too.
How many phones can I run?+
Each account can have 3 phones at a time. A phone runs one goal at a time; a second run on the same phone gets 409 until the first ends.
Do I pay while a phone is idle?+
For up to 5 minutes. After 5 minutes without use the phone falls asleep and costs nothing until you use it again. After 1 hour without use it is deleted.
Can my own agent control the phone?+
Yes. Give it the screenshot and elements endpoints and the actions endpoint as tools, or let it start runs of our phone agent for the parts it would rather hand off.
Can someone watch or help the agent?+
Yes. A live screen link shows the phone in any browser and lets the person tap and type. When the agent needs a code or a choice, it waits for your reply.
Every field, limit and error is in the phone API reference. To give an agent a browser instead of a phone, see the browser agent.