task.listMessages
Lists event messages for a task with cursor-based pagination. Use this to poll for progress after task.create or task.sendMessage. See the Task Lifecycle guide for how to handle each status.
curl --request GET \
--url 'https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10' \
--header 'x-manus-api-key: <api-key>'import requests
url = "https://api.manus.ai/v2/task.listMessages"
headers = {
"x-manus-api-key": "<api-key>"
}
response = requests.get(url, headers=headers, params={
"task_id": "<string>",
"order": "desc",
"limit": "10"
})
print(response.text)const options = {
method: 'GET',
headers: {'x-manus-api-key': '<api-key>'}
};
fetch('https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-manus-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-manus-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10")
.header("x-manus-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-manus-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"ok": true,
"request_id": "<string>",
"task_id": "<string>",
"messages": [
{
"id": "<string>",
"type": "user_message",
"timestamp": 123,
"user_message": {
"content": "<string>",
"message_type": "text",
"attachments": [
{
"type": "image",
"filename": "<string>",
"url": "<string>",
"path": "<string>",
"content_type": "<string>",
"file_uid": "<string>",
"version_uid": "<string>"
}
],
"hidden_content": [
"<string>"
]
},
"assistant_message": {
"content": "<string>",
"attachments": [
{
"type": "image",
"filename": "<string>",
"url": "<string>",
"path": "<string>",
"content_type": "<string>",
"file_uid": "<string>",
"version_uid": "<string>"
}
],
"question_expectation": {
"options": [
"<string>"
],
"selection_mode": "single",
"response_method": "send_message"
},
"delivery_kind": "progress"
},
"error_message": {
"error_type": "<string>",
"content": "<string>"
},
"status_update": {
"agent_status": "running",
"status_detail": {
"waiting_for_event_id": "<string>",
"waiting_for_event_type": "<string>",
"waiting_description": "<string>",
"confirm_input_schema": {}
},
"brief": "<string>",
"description": "<string>"
},
"tool_used": {
"tool": "<string>",
"action_id": "<string>",
"status": "success",
"brief": "<string>",
"description": "<string>",
"message": {
"action": "<string>",
"param": "<string>"
},
"params": {},
"result": {}
},
"plan_update": {
"steps": [
{
"status": "todo",
"title": "<string>",
"started_at": 123,
"end_at": 123
}
]
},
"new_plan_step": {
"step_id": "<string>",
"title": "<string>"
},
"explanation": {
"content": "<string>"
},
"structured_output_result": {
"success": true,
"value": {},
"error": "<string>"
}
}
],
"has_more": true,
"next_cursor": "<string>"
}{
"ok": false,
"request_id": "<string>",
"error": {
"code": "<string>",
"message": "<string>"
}
}- API Key: Full access.
- Standard OAuth client: Requires
create_taskormanage_all_tasks. Withcreate_task, only tasks created by the same client; see Task visibility. - Trusted client: Full access.
status_update events and respond as described in Task Lifecycle. Answer agent questions with task.sendMessage; confirm actions with task.confirmAction.Render output: Resolve file paths and manus-webdev:// links in assistant content as described in Attachments.Headers
API key for direct authentication. Provide either this or Authorization, not both. See Authentication.
Query Parameters
The unique identifier of the task to list messages for. Supports the shortcut agent-default-main_task for the IM agent's main task.
Number of messages to return per page. Default: 50, Range: 1-200.
Pagination cursor from the previous response's next_cursor field. Omit for the first page.
Start at this event, inclusive. Use a value from messages[].id. Cannot be combined with cursor. The response may still include next_cursor for following pages. If the ID appears only in verbose=true responses, use verbose=true or the event is not found.
Sort direction by timestamp.
desc(default) — newest first.asc— oldest first.
asc, desc Include detailed events.
false(default) —user_message,assistant_message,error_message,status_update, anduser_stoponly.true— alsotool_used(tools the agent invoked),plan_update(plan snapshots),new_plan_step(step additions), andexplanation(agent reasoning).
Format of slides attachments in the response.
html(default) — raw HTML slides.pptx— slides converted to PowerPoint.
html, pptx Format of Markdown attachments in assistant_message.attachments. An attachment is treated as Markdown when its filename ends in .md or .markdown, or its content_type contains markdown.
markdown(default) — the original Markdown file.pdf— Markdown converted to PDF.docx— Markdown converted to Word.
Only url changes: filename, content_type, file_uid, and version_uid still describe the source Markdown file. If conversion fails, url remains the original Markdown download.
Conversion runs before the response is returned, so response time grows with the number and size of Markdown attachments on the page. Pair it with start_event_id and limit=1 to convert only the message you need; do not use it for routine polling or full-page reads.
markdown, pdf, docx Response
Messages retrieved successfully.
Whether the request was successful.
true
Unique identifier for this API request.
The task ID these messages belong to.
Array of task event objects representing the conversation and agent activity.
Hide child attributes
Hide child attributes
Unique identifier for this event.
Event type. Determines which payload field is present. tool_used, plan_update, new_plan_step, and explanation are only included when verbose=true. structured_output_result appears after task completion when a structured_output_schema was provided.
user_message, assistant_message, error_message, status_update, tool_used, plan_update, new_plan_step, explanation, user_stop, structured_output_result Unix timestamp in milliseconds when this event occurred.
Present when type="user_message". Contains a message sent by the user.
Hide child attributes
Hide child attributes
The text content of the user's message.
How the message was sent. "text" for typed input, "voice" for voice input.
text, voice Files or images the user attached to their message.
Hide child attributes
Hide child attributes
Type of attachment.
image— image.file— document.voice— audio recording.slides— presentation slides.
image, file, voice, slides Display name of the attachment file.
URL to download the attachment content.
Optional execution-environment path referenced by the message body. Match it to a Markdown link or image destination, then use url to download the attachment. This path is not itself downloadable.
MIME type of the attachment (e.g., "application/pdf", "image/png").
Stable identifier of the backing output file. Present with version_uid when the attachment has a download URL and file identity. See Attachments.
Stable identifier of the backing output file version. Present with file_uid. See Attachments.
Most integrations can ignore this field. A Trusted public client receives additional application context here when verbose=true. See Hidden application context.
Present when type="assistant_message". Contains a response from the agent.
Hide child attributes
Hide child attributes
The text content of the agent's response.
Files, images, or slides the agent generated as output.
Hide child attributes
Hide child attributes
Type of attachment.
image— image.file— document.voice— audio recording.slides— presentation slides.
image, file, voice, slides Display name of the attachment file.
URL to download the attachment content.
Optional execution-environment path referenced by the message body. Match it to a Markdown link or image destination, then use url to download the attachment. This path is not itself downloadable.
MIME type of the attachment (e.g., "application/pdf", "image/png").
Stable identifier of the backing output file. Present with version_uid when the attachment has a download URL and file identity. See Attachments.
Stable identifier of the backing output file version. Present with file_uid. See Attachments.
Present only for agent questions with non-empty choices. Reply with task.sendMessage, not task.confirmAction. Use the enclosing message id to identify this message; nested event_id is webhook-only and is not required for replies.
Hide child attributes
Hide child attributes
Candidate display text, not option IDs or mandatory exact-match answers. Free-text replies are allowed. Send a non-empty answer in message.content; when there are no choices, listMessages omits question_expectation (webhooks may instead use options: []).
1UI selection hint: single for one candidate or multiple for several. Combine multiple selections into one readable message.content (for example, 'Please export PDF and DOCX.'); no delimiter or structured option-ID array is required. Empty or unknown upstream values normalize to single.
single, multiple Fixed to send_message for ordinary questions, including when the upstream value is absent. This does not invoke task.confirmAction. If an unknown value is encountered, stop automatic dispatch and consult the current documentation; do not fall back to action confirmation.
send_message Optional display recommendation. opening and progress are primarily useful during execution and may be collapsed after the step completes. result is more important and should remain visible. If the value is absent or unrecognized, keep the message visible rather than hiding it.
"progress"
Present when type="status_update". Indicates a change in the agent's processing state.
Hide child attributes
Hide child attributes
The agent's current state. waiting means it needs a question answered or an action confirmed; inspect status_detail.waiting_for_event_type to choose the response endpoint.
running, stopped, waiting, error Additional details when agent_status is waiting. For action confirmations, use waiting_for_event_id with task.confirmAction. Agent questions use task.sendMessage instead.
Hide child attributes
Hide child attributes
Identifies the waiting event. For action confirmations, pass it as event_id to task.confirmAction; question replies use task.sendMessage without this parameter.
Waiting event type: messageAskUser / cascadeAskUser are questions answered with task.sendMessage; supported action types such as gmailSendAction use task.confirmAction, even without confirm_input_schema. Do not automatically confirm unrecognized types.
Human-readable description of what the agent is waiting for.
JSON Schema defining the expected input format for the confirmation, if additional input is needed.
Short summary of the current agent activity.
Detailed description of what the agent is doing.
Present when type="tool_used". Tool events normally require verbose=true. A confirmation target can be fetched with verbose=true and start_event_id=waiting_for_event_id only when the target projects to tool_used. Configuration and OAuth targets do not; attempting this lookup for them returns Event not found.
Hide child attributes
Hide child attributes
Name of the tool that was used (e.g., "browser", "code_executor").
Unique identifier for this tool action.
Tool projection status. pending_confirmation means the operation has not executed and is waiting for task.confirmAction, but some confirmation targets such as Gmail and Calendar retain success while waiting. Determine confirmation state from agent_status=waiting and waiting_for_event_id, not from this field alone.
success, error, rollback, pending_confirmation Short summary of the tool action.
Detailed description of what the tool did.
Human-readable display summary for the tool invocation. This is not the structured tool input.
Hide child attributes
Hide child attributes
Human-readable label describing the tool action. The action may still be awaiting confirmation.
Optional human-readable detail shown with the action. This is not the structured tool input; use tool_used.params for structured parameters.
Structured parameters supplied to the tool. Returned when the confirmation target is fetched with verbose=true and start_event_id=waiting_for_event_id, or when that target and its waiting status are returned on the same page. Use them to review the proposed operation; do not submit them directly as task.confirmAction input.
Optional structured tool result used as confirmation context for result-driven operations, such as selecting an account or publishing prepared media. Returned under the same conditions as params.
Present when type="plan_update" (verbose=true only). A full snapshot of the agent's current execution plan.
Hide child attributes
Hide child attributes
All steps in the current plan with their statuses.
Hide child attributes
Hide child attributes
Current status of this plan step.
todo, doing, done, failed Description of this plan step.
Unix timestamp when this step started. Null if not yet started.
Unix timestamp when this step finished. Null if not yet completed.
Present when type="structured_output_result". Contains the extracted structured data. Appears after the status_update (stopped) event when the task was created with a structured_output_schema.
Hide child attributes
Hide child attributes
Whether the agent produced a meaningful result. When false, value contains schema-conforming defaults and error explains what happened.
The extracted value conforming to the schema provided in structured_output_schema. Always present and valid, even when success is false — see zero-value rules.
Error description when success is false. Null when success is true.
Whether there are more messages beyond this page.
Cursor for fetching the next page. Only present when has_more is true.
Was this page helpful?
curl --request GET \
--url 'https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10' \
--header 'x-manus-api-key: <api-key>'import requests
url = "https://api.manus.ai/v2/task.listMessages"
headers = {
"x-manus-api-key": "<api-key>"
}
response = requests.get(url, headers=headers, params={
"task_id": "<string>",
"order": "desc",
"limit": "10"
})
print(response.text)const options = {
method: 'GET',
headers: {'x-manus-api-key': '<api-key>'}
};
fetch('https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-manus-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-manus-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10")
.header("x-manus-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.manus.ai/v2/task.listMessages?task_id=<string>&order=desc&limit=10")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-manus-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"ok": true,
"request_id": "<string>",
"task_id": "<string>",
"messages": [
{
"id": "<string>",
"type": "user_message",
"timestamp": 123,
"user_message": {
"content": "<string>",
"message_type": "text",
"attachments": [
{
"type": "image",
"filename": "<string>",
"url": "<string>",
"path": "<string>",
"content_type": "<string>",
"file_uid": "<string>",
"version_uid": "<string>"
}
],
"hidden_content": [
"<string>"
]
},
"assistant_message": {
"content": "<string>",
"attachments": [
{
"type": "image",
"filename": "<string>",
"url": "<string>",
"path": "<string>",
"content_type": "<string>",
"file_uid": "<string>",
"version_uid": "<string>"
}
],
"question_expectation": {
"options": [
"<string>"
],
"selection_mode": "single",
"response_method": "send_message"
},
"delivery_kind": "progress"
},
"error_message": {
"error_type": "<string>",
"content": "<string>"
},
"status_update": {
"agent_status": "running",
"status_detail": {
"waiting_for_event_id": "<string>",
"waiting_for_event_type": "<string>",
"waiting_description": "<string>",
"confirm_input_schema": {}
},
"brief": "<string>",
"description": "<string>"
},
"tool_used": {
"tool": "<string>",
"action_id": "<string>",
"status": "success",
"brief": "<string>",
"description": "<string>",
"message": {
"action": "<string>",
"param": "<string>"
},
"params": {},
"result": {}
},
"plan_update": {
"steps": [
{
"status": "todo",
"title": "<string>",
"started_at": 123,
"end_at": 123
}
]
},
"new_plan_step": {
"step_id": "<string>",
"title": "<string>"
},
"explanation": {
"content": "<string>"
},
"structured_output_result": {
"success": true,
"value": {},
"error": "<string>"
}
}
],
"has_more": true,
"next_cursor": "<string>"
}{
"ok": false,
"request_id": "<string>",
"error": {
"code": "<string>",
"message": "<string>"
}
}