Task Lifecycle

^{Questions or issues? Contact us at api-support@manus.ai.} After creating a task with task.create, the agent runs asynchronously. Use task.listMessages to poll for events and track progress, or set up Webhooks to receive push notifications when task status changes.

curl 'https://api.manus.ai/v2/task.listMessages?task_id=YOUR_TASK_ID&order=desc&limit=10' \
  -H 'x-manus-api-key: YOUR_API_KEY'

Task status

Look for status_update events in the response. The agent_status field tells you what to do next:

agent_status	Meaning	Action
`running`	Agent is working	Keep polling
`stopped`	Task completed	Read `assistant_message` events for results
`waiting`	Needs user confirmation or input	Handle based on event type (see below)
`error`	Task failed	Read `error_message` for details

Handling `waiting` status

When agent_status is waiting, the status_detail tells you what the agent needs:

{
    "type": "status_update",
    "status_update": {
        "agent_status": "waiting",
        "status_detail": {
            "waiting_for_event_id": "evt_abc123",
            "waiting_for_event_type": "gmailSendAction",
            "waiting_description": "Send email to user@example.com",
            "confirm_input_schema": {
                "type": "object",
                "properties": {
                    "accept": { "type": "boolean" },
                    "save_draft": { "type": "boolean" }
                }
            }
        }
    }
}

There are two ways to respond, depending on waiting_for_event_type:

messageAskUser or cascadeAskUser — The agent is asking a question. Reply with task.sendMessage. Do not use task.confirmAction.
Action confirmations — Use task.confirmAction for supported action types, including those without confirm_input_schema. When present, the schema describes the expected input; otherwise use the documented input for that action below. Schema presence is not the routing criterion.

For an unrecognized waiting type, inspect the task and current endpoint documentation before responding; do not automatically treat it as an action to approve. When the agent supplies choices, the corresponding assistant_message includes a question_expectation object:

{
  "id": "ask_abc123",
  "type": "assistant_message",
  "assistant_message": {
    "content": "Which formats should I export?",
    "question_expectation": {
      "options": ["PDF", "DOCX"],
      "selection_mode": "multiple",
      "response_method": "send_message"
    }
  }
}

options contains display text, not option IDs or an enforced answer schema. Render single- or multiple-choice controls according to selection_mode, while allowing a free-text answer instead. Send a non-empty answer as ordinary message.content through task.sendMessage. For multiple choices, combine the selected text into one readable message, for example:

{
  "task_id": "task_abc123",
  "message": { "content": "Please export both PDF and DOCX." }
}

There is no required delimiter, option-ID array, or structured submission format. Do not submit an empty answer when nothing is selected; ask the user for text instead. response_method is currently fixed to send_message, never task.confirmAction. If a client encounters an unknown method, stop automatic dispatch and check the current API documentation rather than falling back to action confirmation. In task.listMessages, question_expectation is omitted for questions with no choices; use the question’s text and waiting event type to request a free-text answer. When present, options is non-empty. Webhooks can also describe a free-text question with options: []. The nested question_expectation.event_id exists only in webhooks and identifies the underlying question event. It is different from the webhook envelope’s event_id, which identifies the webhook notification. In task.listMessages, use the enclosing message’s id; there is no nested event_id. Neither question ID is required by task.sendMessage, and it is not a send-message idempotency key.

Using `task.confirmAction`

curl -X POST 'https://api.manus.ai/v2/task.confirmAction' \
  -H 'x-manus-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "YOUR_TASK_ID",
    "event_id": "evt_abc123",
    "input": { "accept": true }
  }'

The input format varies by waiting_for_event_type. The table below lists currently supported event types — new types may be added in the future. When present, use confirm_input_schema for the definitive schema; its absence does not turn an action confirmation into an agent question.

Event Type	Description	Example Input
`needConnectMyBrowser`	Select a browser from browser.onlineList, or skip	`{ "action": "select", "client_id": "..." }` or `{ "action": "skip" }`
`gmailSendAction`	Confirm send, or save as draft	`{ "accept": true }` or `{ "accept": true, "save_draft": true }`
`outlookSendMailsAction`	Confirm send, or save as draft	`{ "accept": true }` or `{ "accept": true, "save_draft": true }`
`deployAction`	Confirm deploy. Set `global_allow` to skip future confirmations	`{ "accept": true, "global_allow": true }`
`terminalExecute`	Confirm command. Set `always_allow` to skip future confirmations	`{ "accept": true, "always_allow": true }`
`videoGenerate`	Select video quality: `standard` (default) or `premium`	`{ "choice": "standard" }`
`apiHighCreditNotice`	Respond to high-credit notice: `accept`, `reject`, or `do_not_show_again`	`{ "action": "accept" }`
`googleCalendarCreate`	Confirm calendar event creation	`{ "accept": true }`
`googleCalendarUpdate`	Confirm calendar event update	`{ "accept": true }`
`googleCalendarDelete`	Confirm calendar event deletion	`{ "accept": true }`
`outlookCalendarCreate`	Confirm calendar event creation	`{ "accept": true }`
`outlookCalendarUpdate`	Confirm calendar event update	`{ "accept": true }`
`outlookCalendarDelete`	Confirm calendar event deletion	`{ "accept": true }`
`metaMarketingAction`	Confirm marketing action. Optionally select ad accounts via `selectedAccountIds`	`{ "accept": true, "selectedAccountIds": ["act_123"] }`
`metaMarketingActionResult`	Confirm marketing result. Optionally specify `mode`	`{ "accept": true }`
`webdevRunAction`	Run web app. `mode`: `quality` / `speed` (default) / `max`	`{ "accept": true, "mode": "speed" }`
`webdevRunAction` (deploy)	Deploy web app. `visibility`: `owner` (default) / `team` / `public`	`{ "accept": true, "visibility": "owner" }`
`webdevRequestSecrets`	Provide secrets as `[{key, value}]` array, or reject with `accept: false`	`{ "accept": true, "secrets": [{"key": "X", "value": "Y"}] }`
`connectorOauthExpired`	Re-authorize expired connector	`{ "accept": true }`
`mapreduceAction`	Confirm map-reduce operation	`{ "accept": true }`

For event types that support accept, passing accept: false will not produce any event — the task remains in waiting status. Exception: webdevRequestSecrets where accept: false explicitly rejects the request.

Using My Browser

You can let the agent use your local browser. When the agent needs a browser during execution, it will trigger a needConnectMyBrowser waiting event. Use browser.onlineList to get available clients, then select one via task.confirmAction:

# 1. Get online browser clients
curl 'https://api.manus.ai/v2/browser.onlineList' \
  -H 'x-manus-api-key: YOUR_API_KEY'

# 2. When needConnectMyBrowser event is received, select a browser
curl -X POST 'https://api.manus.ai/v2/task.confirmAction' \
  -H 'x-manus-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "YOUR_TASK_ID",
    "event_id": "evt_abc123",
    "input": { "action": "select", "client_id": "0e9ad711-8471-4fcc-a9de-8309f0f12c87" }
  }'

If browser.onlineList returns an empty list, no browser clients are online. Install and enable the Manus Browser Extension first.

Complete flow

1. POST /v2/task.create          → Create task (optionally with structured_output_schema)
2. GET  /v2/task.listMessages    → Poll for events
   ├─ agent_status=running       → Keep polling
   ├─ agent_status=waiting       → Check waiting_for_event_type
   │   ├─ messageAskUser / cascadeAskUser → POST /v2/task.sendMessage
   │   ├─ needConnectMyBrowser   → POST /v2/task.confirmAction (select browser)
   │   ├─ Supported action types → POST /v2/task.confirmAction (schema optional)
   │   └─ Unrecognized types     → Inspect before responding; do not auto-approve
   ├─ agent_status=stopped       → Task complete, read results
   │   └─ structured_output_result → Extracted JSON (if schema was provided)
   └─ agent_status=error         → Task failed, read error details

Structured Output: If you need the result in a specific JSON format, pass structured_output_schema when creating the task. See the Structured Output guide.

Getting Started

API Reference

Task status

Handling `waiting` status

Using `task.confirmAction`

Using My Browser

Complete flow

​Task status

​Handling waiting status

​Using task.confirmAction

​Using My Browser

​Complete flow

Task status

Handling `waiting` status

Using `task.confirmAction`

Using My Browser

Complete flow