Skip to main content
Starts a task: one natural-language instruction executed on the device. Returns task_id immediately - execution is asynchronous, and you follow up with phone_task_monitor to wait for the outcome. This is the workhorse of the API. In most workflows it is the only tool you configure; sessions and device selection are handled for you.

​
Parameters

​
string
required
The instruction to execute, in plain language. See Task design for what makes prompts execute reliably.
​
string
Attach the task to an existing workflow. Omit it and the server creates or reuses a session automatically, returning its session_id.
​
string
Target a specific device. Omit to use your default device. Ignored in favor of the session’s device when session_id is provided - a session is bound to one phone.
​
integer
default:"300"
Execution deadline in seconds. Maximum 900. Tasks that exceed it complete with terminal: "timeout". Time spent paused does not count.
​
integer
default:"60"
How long the task may wait for the phone to start it. Maximum 300. Tasks that never start complete with terminal: "queue_wait_exceeded".
For benchmarking and data-collection runs, phone_run_task also accepts optional trace tags: run_id (string), run_type (string), and task_metadata (object). Leave them unset for normal use.

​
Response

​
string
Returned immediately. Pass it to phone_task_monitor to wait for the outcome, and to task-control tools to steer, pause, or cancel.
​
string
The session that was created or reused. Pass it on later calls to keep related tasks in one workflow.

​
Behavior

Starting a new phone_run_task on the same device cancels any existing pending, running, or paused MCP task on that device (it completes with terminal: "stopped_by_user"). Tasks started from the phone app itself are not cancelled; they occupy the device’s execution lane and can keep a new MCP task pending until they finish.
  • One instruction, one task. For a multi-step workflow, run several tasks in the same session rather than one enormous prompt - see Session management.
  • Long flows benefit from a higher per_call_timeout_s; tasks that hit the agent’s action limit complete with terminal: "iteration_limit" and should be broken into smaller steps.

​
Example