> ## Documentation Index
> Fetch the complete documentation index at: https://open.manus.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# task.list
> Lists tasks with optional filtering and cursor-based pagination. Use `scope` to filter by task type, e.g. `agent_subtask` with `agent_id` for agent subtasks. See [task.detail](https://open.manus.ai/docs/v2/task.detail) for full details on a specific task.
Questions or issues? Contact us at [api-support@manus.ai](mailto:api-support@manus.ai).
**OAuth scope:** `create_task` or `manage_all_tasks` — see the [Open App](https://open.manus.ai/docs/v2/open-app) guide. With `create_task` scope, only returns tasks created by this Open App. `manage_all_tasks` returns all of the user's tasks.
**Scope:** Filter by task type — `standard` for regular tasks, `project` with `project_id` for project tasks, `agent_subtask` with `agent_id` for agent subtasks.
**Shortcut:** Use `agent-default` as `agent_id` for the IM agent. See the [Agents](https://open.manus.ai/docs/v2/agents-overview) guide.
**Filter by credential:** Use `oauth_client_id` or `api_key_id` to return only tasks created by a specific Open App or API key. The two parameters are mutually exclusive. OAuth tokens with only the `create_task` scope are already limited to their own app's tasks: they cannot filter by `api_key_id` or by another app's `oauth_client_id`.
## OpenAPI
````yaml GET /v2/task.list
openapi: 3.1.0
info:
title: Manus OpenAPI v2
description: >-
API for integrating Manus into your workflow. All responses are wrapped with
{"ok": true, "request_id": "...", ...} for success and {"ok": false,
"request_id": "...", "error": {"code": "...", "message": "..."}} for errors.
version: 2.0.0
servers:
- url: https://api.manus.ai
security:
- ApiKeyAuth: []
paths:
/v2/task.list:
get:
summary: ListTasks
description: >-
Lists tasks with optional filtering and cursor-based pagination. Use
`scope` to filter by task type, e.g. `agent_subtask` with `agent_id` for
agent subtasks. See
[task.detail](https://open.manus.ai/docs/v2/task.detail) for full
details on a specific task.
operationId: openapi.v2.OpenapiV2Service.ListTasks
parameters:
- name: x-manus-api-key
in: header
required: false
schema:
type: string
description: >-
API key for direct authentication. Provide either this or
`Authorization`, not both. See
[Authentication](https://open.manus.ai/docs/v2/authentication).
- name: Authorization
in: header
required: false
schema:
type: string
example: Bearer {access_token}
description: >-
OAuth2 access token in `Bearer {token}` format. Provide either this
or `x-manus-api-key`, not both. See the [Open
App](https://open.manus.ai/docs/v2/open-app) guide.
- name: limit
in: query
schema:
type: integer
description: 'Number of tasks to return per page. Default: 20, Max: 100.'
- name: cursor
in: query
schema:
type: string
description: >-
Pagination cursor from the previous response's next_cursor field.
Omit for the first page.
- name: order
in: query
schema:
type: string
enum:
- asc
- desc
description: >-
Sort direction by creation time. "desc" (default) returns newest
first, "asc" returns oldest first.
- name: scope
in: query
schema:
type: string
enum:
- all
- agent_subtask
- project
- standard
description: >-
Filter by task type. "all" (default) returns all tasks. "standard"
returns regular tasks. "project" returns tasks within a project
(requires project_id). "agent_subtask" returns subtasks created by
an agent (requires agent_id).
- name: agent_id
in: query
schema:
type: string
description: >-
Filter tasks by agent. Required when scope="agent_subtask".
Supports the shortcut `agent-default` for the IM agent. Use
[agent.list](https://open.manus.ai/docs/v2/agent.list) to get
available agent IDs.
- name: project_id
in: query
schema:
type: string
description: >-
Filter tasks by project. Required when scope="project". Use
[project.list](https://open.manus.ai/docs/v2/project.list) to get
available project IDs.
- name: oauth_client_id
in: query
schema:
type: string
description: >-
Filter tasks by the Open App (OAuth client) that created them.
Mutually exclusive with api_key_id — passing both returns an
invalid_argument error. OAuth tokens with only the create_task
scope are already limited to their own app's tasks and may only
pass their own client ID; passing another app's client ID returns
a permission_denied error. IDs that don't match any of the user's
tasks return an empty list.
- name: api_key_id
in: query
schema:
type: string
description: >-
Filter tasks by the API key that created them. Mutually exclusive
with oauth_client_id — passing both returns an invalid_argument
error. Not available to OAuth tokens with only the create_task
scope (returns a permission_denied error). IDs that don't match
any of the user's tasks return an empty list.
responses:
'200':
description: Tasks retrieved successfully.
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
example: true
description: Whether the request was successful.
request_id:
type: string
description: Unique identifier for this API request.
data:
type: array
items:
$ref: '#/components/schemas/Task'
description: Array of task objects matching the filter criteria.
has_more:
type: boolean
description: >-
Whether there are more tasks beyond this page. If true,
use next_cursor to fetch the next page.
next_cursor:
type: string
description: >-
Cursor to pass as the cursor parameter for the next page.
Only present when has_more is true.
4XX:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security: []
components:
schemas:
Task:
type: object
description: Represents a task with its current status and metadata.
properties:
id:
type: string
description: Unique identifier for the task.
status:
type: string
enum:
- running
- stopped
- waiting
- error
description: >-
Current task status. "running" — agent is actively working.
"stopped" — task has finished or been stopped. "waiting" — agent is
paused and waiting for user input or confirmation. "error" — task
encountered an unrecoverable error.
created_at:
type: integer
format: int64
description: Unix timestamp (seconds) when the task was created.
updated_at:
type: integer
format: int64
description: Unix timestamp (seconds) when the task was last updated.
task_type:
type: string
enum:
- standard
- project
- agent_subtask
description: >-
Type of the task. "standard" — a regular standalone task. "project"
— a task within a project. "agent_subtask" — a subtask created by an
agent. Use [task.list](https://open.manus.ai/docs/v2/task.list) with
`scope` to filter by task type.
share_visibility:
type: string
enum:
- private
- team
- public
description: >-
Who can view the task. "private" — only the task creator. "team" —
all team members. "public" — anyone with the share link.
title:
type: string
description: Title of the task.
credit_usage:
type: integer
format: int32
description: >-
Total credits consumed by the task. Only present when the task has
consumed credits.
task_url:
type: string
description: >-
URL to view the task in the Manus webapp (e.g.,
https://manus.im/app/{task_id}).
created_by_api_key:
type: object
nullable: true
description: >-
The API key that created this task. Present when the task was
created via the API; null or absent when created through the UI or
other means. The name reflects the API key's current name, not a
snapshot from creation time.
properties:
id:
type: string
description: The API key ID.
name:
type: string
description: The current display name of the API key.
agent_profile:
type: string
enum:
- manus-1.6
- manus-1.6-lite
- manus-1.6-max
description: >-
Agent profile most recently used by the task — reflects the latest
turn (e.g. an
[task.sendMessage](https://open.manus.ai/docs/v2/task.sendMessage)
override), not just the value supplied at task creation. Omitted
when this information is not available (e.g. older tasks).
ErrorResponse:
type: object
description: Standard error response format returned when a request fails.
properties:
ok:
type: boolean
example: false
description: Always false for error responses.
request_id:
type: string
description: >-
Unique identifier for this API request, useful for debugging with
support.
error:
type: object
description: Error details.
properties:
code:
type: string
description: >-
Machine-readable error code (e.g., "invalid_argument",
"not_found", "permission_denied", "rate_limited").
message:
type: string
description: Human-readable error description explaining what went wrong.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-manus-api-key
````