Needs SDK 6.2.0 or later. Start with the Mobilerun SDK guide.
Devices
Create and wait until ready
Replaces creating a device and polling until it is ready. Creating a device uses device minutes until you stop or terminate it.params must include
deviceType.
If the device does not become ready,
create throws ObjectReadyError.
Stop and resume
A stopped device keeps its data and apps and stops using device minutes. Cloud iOS devices cannot be stopped yet; calldevice.terminate() instead.
stop throws WaitFailureError or WaitTimeoutError. resume throws ObjectReadyError. The device
is not terminated when they happen.
Actions
The device ID is already known to the object.duration is in milliseconds. ui() returns the current accessibility tree of the screen.
Screenshots
device.screenshot() returns a result with bytes, save(), base64() and dataUrl() (Python
data_url()). TypeScript also has blob().
Stream an Android or iOS device
Show a live device in your web app with<DeviceStream /> from
@mobilerun/react. Never send your API key to
the browser. The Mobilerun SDK guide shows the
server and React parts.
- Android
- iPhone
Tasks
Wait for a task
Replaces a status polling loop withsetTimeout or time.sleep. task.wait() returns the final
status once the task completed.
All wait errors extend
WaitError.
Typed output
Pass an output schema todevice.run() and call waitOutput() (Python wait_output()) to get the
result as typed data. TypeScript uses Zod 4 through output() from
@mobilerun/sdk/zod. Python uses a Pydantic model.
result.response is the raw status response. Options are the same as for wait(). It throws
OutputValidationError when the output does not match your schema, plus the errors of wait().
Recordings and files
Recordings
recording.wait() returns once the video is uploaded. Then video() and trajectory() return the
files as bytes.
task.wait().
Saved screenshots
Save a screenshot withdevice.screenshot({ save: true }) (Python save=True). savedScreenshot.image()
returns the PNG as bytes. device.screenshots.list() returns one page; read its saved screenshots from
.items.
Agent files
agentFile.download() returns the file as bytes.
Uploads
Upload an app
Uploads the files and returns anApp. A string is a local file path, and the file streams from disk.
Uploads use storage quota and may incur storage charges.
Upload a file
Uploads the file and returns anAgentFile. A string is a local file path.
Webhooks
Replaces writing the signature check yourself.verifyWebhook (Python verify_webhook) is a standalone
import and needs no API key. Pass the raw request body, exactly as received. If a framework parses the
JSON first, the signature no longer matches. The check also rejects requests that are too old or too far
in the future, so replays fail. Deduplicate replays with an ID inside the signed body, not the unsigned
X-Mobilerun-Event-Id header.
WebhookVerificationError (wrong signature or too old), respond with 400. See
Webhooks for events and secrets.
Common to all objects
- Pagination. Lists are iterated directly:
for await (const device of mobilerun.devices.list())in TypeScript,for device in mobilerun.devices.list()in Python. Next pages load as needed. fromId().mobilerun.devices.fromId(id)(Pythonfrom_id) gives you an object without a network call. Every collection, such asmobilerun.tasks, has it.- Automatic cleanup.
await using(TypeScript 5.2 or later) andwith(Python) terminate a device fromdevices.create()when the block ends. Devices fromget,fromIdor a list are never cleaned up for you. - Safe logging. Objects never print the API key.
console.log(device)andprint(device)are safe.
Mobilerun SDK
Create devices, run tasks, stream, and the list of all objects.
Cloud Quickstart
Run your first task end to end.