MOBILERUN_API_KEY

1. Check for devices:
   bash

   curl -s https://api.mobilerun.ai/v1/devices \
     -H "Authorization: Bearer $MOBILERUN_API_KEY"

   • 200

     with a device in

     state: "ready"

     = good to go, skip all setup, just do what the user asked

   • 200

     but no devices or all

     state: "disconnected"

     = device issue (see step 2)

   • 401

     = key is invalid, expired, or revoked -- ask the user to check https://cloud.mobilerun.ai/api-keys
2. Only if no ready device: tell the user the device status and suggest a fix:
   • No devices at all = user hasn't connected a phone yet, guide them to Portal APK (see reference.md)
   • Device with

     state: "disconnected"

     = Portal app lost connection, ask user to reopen it
3. Confirm device is responsive (optional, only if first action fails):
   bash

   curl -s https://api.mobilerun.ai/v1/devices/{deviceId}/screenshot \
     -H "Authorization: Bearer $MOBILERUN_API_KEY" -o screenshot.png

   If this returns a PNG image, the device is working.

ready

disconnected

streamUrl

streamToken

assignedAt

terminatesAt

taskCount

disconnected

DELETE /devices/{deviceId}

MOBILERUN_API_KEY

GET /devices

• state

  -- filter by state (array, e.g.

  state=ready&state=assigned

  )

• type

  --

  dedicated_emulated_device

  ,

  dedicated_physical_device

  ,

  dedicated_premium_device

• name

  -- filter by device name (partial match)

• page

  (default: 1),

  pageSize

  (default: 20)

• orderBy

  --

  id

  ,

  createdAt

  ,

  updatedAt

  ,

  assignedAt

  (default:

  createdAt

  )

• orderByDirection

  --

  asc

  ,

  desc

  (default:

  desc

  )

{ items: DeviceInfo[], pagination: Meta }

403

POST /devices
Content-Type: application/json

{
  "name": "my-device",
  "apps": ["com.example.app"]
}

• deviceType

  --

  dedicated_emulated_device

  ,

  dedicated_physical_device

  ,

  dedicated_premium_device

GET /devices/{deviceId}/wait

ready

1. POST /devices?deviceType=dedicated_emulated_device

   -- provision, returns device in

   creating

   state

2. GET /devices/{deviceId}/wait

   -- blocks until

   ready

3. Use the

   deviceId

   for phone control or tasks

1. POST /devices?deviceType=dedicated_emulated_device

   with

   {"name": "temp-task-device", "apps": [...]}

   -- include any apps the task needs

2. GET /devices/{deviceId}/wait

   -- wait until ready

3. POST /tasks

   with the new

   deviceId

   -- run the task
4. Monitor via

   GET /tasks/{taskId}/status

   until the task finishes

5. DELETE /devices/{deviceId}

   -- terminate the device after the task completes (or fails)

DELETE /devices/{deviceId}
Content-Type: application/json

{}

Personal devices cannot be terminated via the API. They disconnect when the Portal app is closed.

{
  "keyboardVisible": false,
  "packageName": "app.lawnchair",
  "currentApp": "Lawnchair",
  "isEditable": false,
  "focusedElement": {
    "className": "string",
    "resourceId": "string",
    "text": "string"
  }
}

• currentApp

  -- human-readable name of the foreground app

• packageName

  -- Android package name of the foreground app

• keyboardVisible

  -- whether the soft keyboard is showing

• isEditable

  -- whether the currently focused element accepts text input

• focusedElement

  -- details about the focused UI element (if any)

{
  "screen_bounds": { "width": 720, "height": 1616 },
  "display_metrics": {
    "density": 1.75,
    "densityDpi": 280,
    "scaledDensity": 1.75,
    "widthPixels": 720,
    "heightPixels": 1616
  },
  "filtering_params": {
    "min_element_size": 5,
    "overlay_offset": 0
  }
}

• screen_bounds

  -- the actual screen resolution in pixels. All tap/swipe coordinates use this coordinate space.

• display_metrics

  -- physical display properties (density, DPI)

{
  "className": "android.widget.TextView",
  "packageName": "app.lawnchair",
  "resourceId": "app.lawnchair:id/search_container",
  "text": "Search",
  "contentDescription": "",
  "boundsInScreen": { "left": 48, "top": 1420, "right": 671, "bottom": 1532 },
  "isClickable": true,
  "isLongClickable": false,
  "isEditable": false,
  "isScrollable": false,
  "isEnabled": true,
  "isVisibleToUser": true,
  "isCheckable": false,
  "isChecked": false,
  "isFocusable": false,
  "isFocused": false,
  "isSelected": false,
  "isPassword": false,
  "hint": "",
  "childCount": 0,
  "children": []
}

• text

  -- the visible text on the element

• contentDescription

  -- accessibility label (useful when

  text

  is empty, e.g. icon buttons)

• resourceId

  -- Android resource ID (e.g.

  com.app:id/button_ok

  ) -- useful for identifying elements

• boundsInScreen

  -- pixel coordinates as

  {left, top, right, bottom}

  . To tap an element, calculate its center:

  x = (left + right) / 2

  ,

  y = (top + bottom) / 2

• isClickable

  -- whether the element responds to taps

• isEditable

  -- whether the element is a text input field

• isScrollable

  -- whether the element supports scrolling (swipe gestures)

• children

  -- nested child elements (the tree is recursive)

FrameLayout (0,0,720,1616)
  ScrollView (0,0,720,1616) [scrollable]
    FrameLayout (14,113,706,326)
      LinearLayout (42,128,706,310) [clickable]
        TextView (42,156,706,198) "Tap to set up"
  View (0,94,720,1574) "Home"
  TextView (14,1222,187,1422) "Phone" [clickable]
  TextView (187,1222,360,1422) "Contacts" [clickable]
  TextView (360,1222,533,1422) "Files" [clickable]
  TextView (533,1222,706,1422) "Chrome" [clickable]
  FrameLayout (48,1420,671,1532) "Search" [clickable]

filter=true

POST /devices/{deviceId}/swipe
Content-Type: application/json

{
  "startX": 540,
  "startY": 1200,
  "endX": 540,
  "endY": 400,
  "duration": 300
}

duration

• Scroll down: swipe from bottom to top (high startY -> low endY)
• Scroll up: swipe from top to bottom
• Swipe left/right: adjust X coordinates, keep Y similar

POST /devices/{deviceId}/keyboard
Content-Type: application/json

{ "text": "Hello world", "clear": false }

• clear: true

  -- clears the field before typing
• Make sure an input field is focused first (check

  phone_state.isEditable

  )
• If the keyboard isn't visible, you may need to tap on an input field first

POST /devices/{deviceId}/apps
Content-Type: application/json

{ "packageName": "com.example.app" }

GET /devices/{id}/apps

On personal devices, this endpoint may fail because Android blocks app installations from unknown sources by default.

GET /apps

• page

  (default: 1),

  pageSize

  (default: 10)

• source

  --

  all

  ,

  uploaded

  ,

  store

  ,

  queued

  (default:

  all

  )

• query

  -- search by name

• sortBy

  --

  createdAt

  ,

  name

  (default:

  createdAt

  )

• order

  --

  asc

  ,

  desc

  (default:

  desc

  )

1. Find the existing app:

   GET /apps?query=com.example.myapp

2. Delete it:

   DELETE /apps/{id}

3. Upload the new version using the 3-step upload flow above

POST /tasks
Content-Type: application/json

{
  "task": "Open Chrome and search for weather",
  "deviceId": "uuid-of-device",
  "llmModel": "google/gemini-3.1-flash-lite-preview"
}

• task

  -- natural language description of what to do (min 1 char)

• deviceId

  -- UUID of the device to run on. Must be a device in

  ready

  state.

• llmModel

  -- which model to use (default:

  google/gemini-3.1-flash-lite-preview

  , see

  GET /models

  for available models)

• apps

  -- list of app package names to pre-install

• credentials

  -- list of

  { packageName, credentialNames[] }

  for app logins

• maxSteps

  -- max agent steps (default: 100)

• reasoning

  -- enable reasoning/thinking (default: true). Always set to

  false

  unless the user explicitly requests it.

• vision

  -- enable vision/screenshot analysis (default: false)

• temperature

  -- LLM temperature (default: 0.5)

• executionTimeout

  -- timeout in seconds (default: 1000)

• outputSchema

  -- JSON schema for structured output (nullable). Only use when the user explicitly asks for structured/formatted data. When set, the agent returns its result as a JSON object matching the schema in the task's

  output

  field.

• vpnCountry

  -- route through VPN in a specific country:

  US

  ,

  BR

  ,

  FR

  ,

  DE

  ,

  IN

  ,

  JP

  ,

  KR

  ,

  ZA

  . Only use if the task specifically requires a certain region. VPN adds latency -- avoid unless needed.

{
  "id": "uuid",
  "streamUrl": "string"
}

• Bad:

  "Tap the three dots menu in the top right, then tap Settings, scroll down and tap the Dark Mode toggle"

• Good:

  "Open Settings in the Chrome app and enable Dark Mode"

• You don't know what the screen looks like. The on-device agent can see it -- let it handle the navigation.

• Name the exact app (not "the browser" -- say "Chrome")
• Specify exact text to type or send
• Say what counts as success
• Name the person, contact, or item to find

"Open the Settings app, go to Display, and enable Dark Mode"

"Open WhatsApp, find the conversation with John Smith, and send: Running 10 minutes late, sorry!"

"Open Chrome, go to amazon.com, search for 'wireless headphones', and report back the name and price of the top 3 results"

"Open Chrome, go to docs.google.com/forms/d/abc123, and fill in the form with: Name = Sarah Connor, Email = sarah@example.com, Department = Engineering. Then submit the form."

"Open Spotify, go to Settings, turn off Autoplay, set Audio Quality to Very High, and disable Canvas"

"Open Gmail, check if there are any unread emails from support@stripe.com in the last 24 hours, and tell me the subject lines"

"Open Google Maps, search for 'Italian restaurants near me', find the highest rated one that's currently open, then open Chrome and search for that restaurant's menu"

• Bad:

  "Order me an Uber to work"

• Good:

  "Open the Uber app, set the destination to 123 Main Street, select UberX, and stop before confirming the ride so I can review the price"

• "If the app asks for login, stop and tell me"

• "If the price is over $50, don't purchase -- just report the price"

GET /tasks/{task_id}/status

{
  "status": "running",
  "succeeded": null,
  "message": null,
  "output": null,
  "steps": 5,
  "lastResponse": { "event": "ManagerPlanEvent", "data": { ... } }
}

• While running:

  lastResponse

  contains the agent's latest thinking, plan, and actions. Check this to understand what the agent is doing and where it's up to.
• When finished:

  status

  is

  completed

  or

  failed

  ,

  message

  has the final answer or failure reason,

  succeeded

  is

  true

  /

  false

  ,

  lastResponse

  is

  null

  .
• Statuses:

  created

  ,

  running

  ,

  paused

  ,

  completed

  ,

  failed

  ,

  cancelled

1. Immediately tell the user the task is running (task ID, what it's doing).
2. After 5 seconds -- do the first status check. This catches quick tasks and confirms the agent started.
3. After 30 seconds -- check again if still running.
4. Subsequent checks -- use your judgement on the interval based on:
   • Task complexity -- a simple "open Chrome" task finishes fast; a multi-app workflow takes longer, so space out checks accordingly.
   • Progress -- if steps are increasing and

     lastResponse

     is changing, the agent is working well; you can wait longer between checks. If the step count and

     lastResponse

     haven't changed, the agent may be stuck; check sooner and consider warning the user.
   • Time elapsed -- the longer a task has been running successfully, the more you can trust it and wait between checks.

• Report to the user what the agent is doing (from

  lastResponse

  -- its current plan, thinking, what step it's on).
• Optionally take a screenshot (

  GET /devices/{id}/screenshot

  ) to show the user what's on screen.
• Optionally read the UI state (

  GET /devices/{id}/ui-state

  ) for more context.
• Give the user a meaningful update, not just "still running" -- e.g. "The agent is on step 8, currently in the Settings app looking for display options."

• Report the result (

  message

  ,

  succeeded

  ,

  output

  ).
• If the task failed unexpectedly, auto-submit feedback (see Feedback section).

• Send a message via

  POST /tasks/{id}/message

  to nudge it in the right direction.
• Let the user know and ask if they want to steer it or cancel.

GET /tasks

• status

  --

  created

  ,

  running

  ,

  paused

  ,

  completed

  ,

  failed

  ,

  cancelled

• orderBy

  --

  id

  ,

  createdAt

  ,

  finishedAt

  ,

  status

  (default:

  createdAt

  )

• orderByDirection

  --

  asc

  ,

  desc

  (default:

  desc

  )

• query

  -- search in task description (max 128 chars)

• page

  (default: 1),

  pageSize

  (default: 20, max: 100)

• When a task fails unexpectedly
• When the agent behaves incorrectly or produces wrong results
• When API errors occur that seem like platform bugs
• Include the

  taskId

  , error details, and what happened

• Ask for a few details (what happened, what they expected) but don't push hard
• If they don't want to elaborate, just submit with whatever details you have

POST /feedback
Content-Type: application/json

{
  "title": "Task failed unexpectedly",
  "feedback": "The agent got stuck on the login screen and timed out after 50 steps.",
  "rating": 2,
  "taskId": "uuid-of-related-task"
}

• title

  -- short summary (3-100 chars)

• feedback

  -- detailed description (10-4000 chars)

• rating

  -- 1 to 5

• taskId

  -- UUID of a related task

201

400

401

429

1. Take a screenshot and/or read the UI state
2. Decide what action to perform
3. Execute the action (tap, type, swipe, etc.)
4. Observe again to verify the result
5. Repeat

GET /devices/{id}/ui-state?filter=true

x = (left + right) / 2

y = (top + bottom) / 2

• Take a screenshot and re-read the UI state -- the screen may have changed or your tap coordinates may have been off.
• If an element isn't visible, try scrolling (swipe up/down) to reveal it.
• If a tap didn't register, recalculate coordinates from the latest UI state and try again.
• If the app is unresponsive, try pressing HOME and reopening the app.
• If you're stuck after 2-3 attempts, tell the user what's happening and ask how to proceed.

1. Check

   phone_state.isEditable

   -- if false, tap the input field first
2. Optionally clear existing text with

   clear: true

3. Send the text via

   POST /devices/{id}/keyboard

1. Direct control -- You drive the device step-by-step: screenshot, tap, swipe, type. Best for simple, quick actions on a single device.
2. Mobilerun Agent -- Submit a natural language goal via

   POST /tasks

   and the agent executes it autonomously. Best for complex or multi-step tasks. Monitor progress with

   GET /tasks/{id}/status

   and steer with

   POST /tasks/{id}/message

   . Requires credits (paid plan).

• When the task is complex or spans multiple screens/apps
• When the user asks about approaches or alternatives
• When direct control isn't producing good results
• When managing multiple devices -- always use tasks for multi-device scenarios. Direct control is sequential (one action at a time on one device), so controlling multiple devices by hand is too slow. Submit a task to each device and monitor them in parallel.

1. Split the goal into clear, self-contained sub-goals
2. Submit the first sub-task via

   POST /tasks

3. Wait for it to complete, check the result
4. If it succeeded, submit the next sub-task (the device is already in the right state from the previous task)
5. Repeat until done

1. "Open Instacart and search for 'organic bananas', add the first result to cart"

2. "Search for 'whole milk', add the first result to cart"

3. "Go to cart and report back the total price -- do not checkout"

• Use direct control to quickly set something up (open the right app, navigate to a screen), then launch a task for the complex part.
• Let a task do the heavy lifting, then use direct control for a precise final action (e.g. verify a specific element on screen).
• Use direct control for a quick check (screenshot to see what's on screen), then decide whether to handle it manually or submit a task.