> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# phone_task_monitor

> Wait until a task needs attention or finishes.

Blocks until the task is `paused` or `completed`, or returns `monitor_timed_out: true` after `timeout_s`. This is the entire polling loop: **monitor, check, monitor again.**

Read-only: it never changes task state.

## Parameters

<ParamField body="task_id" type="string" required>
  The task to wait on, as returned by
  [`phone_run_task`](/api-reference/tools/phone-run-task).
</ParamField>

<ParamField body="timeout_s" type="integer" default="120">
  Maximum wait per call, in seconds. 120 is both the default and the cap.
</ParamField>

<ParamField body="include_steps" type="boolean">
  Include the task's recorded steps (screenshots, thinking) in the payload.
</ParamField>

<ParamField body="since_step" type="integer">
  Return only steps newer than this step number. Use with `include_steps` to
  fetch incremental progress without re-downloading history.
</ParamField>

## Response

The task's status payload (the same shape as
[`phone_task_status`](/api-reference/tools/phone-task-status)), plus:

<ResponseField name="monitor_timed_out" type="boolean">
  * `false` - the task is now `paused` or `completed`. Act on it.
  * `true` - the wait ended while the task was still `pending` or `running`.
    Call the monitor again.
</ResponseField>

## What the monitor catches

The monitor returns for **every actionable phone event**, not only successful completion:

* Mobile `message_user`, `needs_confirmation`, `need_login`,
  `need_login_details`, and CAPTCHA actions arrive as a completed task with
  `terminal: "needs_user_control"`.
* A successful mobile `finished` action returns `terminal: "ok"`.
* Errors, cancellation, timeout, queue expiry, offline devices, expired
  sessions, and iteration limits return immediately after they are recorded.

When the task completes, read `terminal` and act on it - the full table is in
[Task lifecycle](/guides/concepts/task-lifecycle#terminal-outcomes).

<Note>
  `monitor_timed_out: true` is not a failure. It exists so your client never
  blocks indefinitely; the task keeps working regardless. A `paused` status is
  actionable too - resume it with
  [`phone_task_resume`](/api-reference/tools/phone-task-resume) and keep
  monitoring the same `task_id`.
</Note>

## Related

* [`phone_task_status`](/api-reference/tools/phone-task-status) - non-blocking snapshot
* [`phone_task_message`](/api-reference/tools/phone-task-message) - answer a `needs_user_control` result
* [Task lifecycle](/guides/concepts/task-lifecycle) - the loop end-to-end