Vigile
SearchContents

DocumentationOperations

list_tasks

List tasks, without their descriptions, with each one's status, links and calculated state. Filter by project, group, type, status, assignee or problems. For a high-level view ask for top_level, which lists the groups and the ungrouped tasks; a group reports its progress. To zoom into a group pass it as parent. Returns at most 100 per call, ordered by ID. To find work that can start now, use list_next_tasks.

The operation's own description: what an agent reads to decide whether and how to call it.
It
Reads. It changes nothing.
Who may call it
Every user.
Pages
Answers in pages of at most 100, with a continuation token for the next.
Answers with
A list of tasks, each in short. Its fields. Not in it: description, why, links, timeline, created_at, created_by, updated_at and unchanged_since. get has those.
MCP tool
list_tasks
HTTP
POST /api/list-tasks
Command
vigile list-tasks

Input

FieldTakesWhat it is
projectstringoptionalOnly tasks inside this project, at any depth.
parentstringoptionalOnly tasks inside this task, at any depth. Use it to zoom into one group.
top_levelbooleanoptionaltrue to list only tasks that are not inside another task: the groups and the ungrouped tasks. Use it for a high-level view.
status"draft" | "open" | "in_progress" | "paused" | "in_review" | "done" | "cancelled"optional
type"task" | "bug" | "issue" | "incident"optionalOnly tasks of this type: task, bug, issue or incident.
assigned_tostringoptionalOnly tasks assigned to this user: a username or user ID.
has_problemsbooleanoptionaltrue to list only tasks that have problems.
continuationstringoptionalThe continuation token from the previous page. Return it unchanged to the same operation with the same filters; stop when no token is returned.

A field that is not listed here is refused, as invalid_input. On the command line each field is an option, with hyphens for underscores: --project.

Example

The same call three ways, as agent1. It was made on the demo plan the pictures of this site show. Over HTTP and MCP, a call without a key acts as agent1 on a new instance.

Command line

vigile list-tasks --project WEB --status open --as agent1

HTTP

curl -s http://127.0.0.1:8700/api/list-tasks \
  -H 'content-type: application/json' \
  -d '{"project":"WEB","status":"open"}'

MCP tool call

{
  "name": "list_tasks",
  "arguments": { "project": "WEB", "status": "open" }
}

The answer

{
  "tasks": [
    {
      "kind": "task",
      "id": "WEB-004",
      "title": "Confirmation email is sent after payment",
      "type": "task",
      "status": "open",
      "priority": 0,
      "value": null,
      "size": null,
      "version": 1,
      "contained_in": ["WEB", "WEB-001"],
      "depends_on": ["WEB-003"],
      "assigned_to": [],
      "is_assigned": false,
      "is_next": false,
      "is_waiting": true,
      "waiting_for": ["WEB-003"],
      "has_problems": false
    },
    {
      "kind": "task",
      "id": "WEB-005",
      "title": "Total is wrong when a coupon is applied twice",
      "type": "bug",
      "status": "open",
      "priority": 9,
      "value": null,
      "size": null,
      "version": 1,
      "contained_in": ["WEB", "WEB-001"],
      "depends_on": [],
      "assigned_to": [],
      "is_assigned": false,
      "is_next": true,
      "is_waiting": false,
      "waiting_for": [],
      "has_problems": false
    }
  ]
}

This is what a service answered when this page was built; for the page, tasks shows 2 of 5. Over HTTP it is the body of the response, over MCP the text of the tool result, and the command line prints it in words unless given --json.

What it answers

tasks: each task in short, without its description: its status, its links, and what is worked out from them. A continuation token is there when more tasks follow. What an answer about a task carries lists the fields.

Rules

  • The filters narrow together: a task is listed when it fits all that are given.
  • project and parent list what is inside, at any depth.
  • top_level: true lists the tasks that are in no other task: the groups and the ungrouped tasks. It is the view from the top; a group reports its progress.
  • has_problems: true lists only tasks with problems; false, only those without.
  • assigned_to takes a username or a user's ID.
  • Deleted tasks are not listed.
  • The order is by ID: tasks whose ID is a number alone first, then by prefix in alphabetical order, and by number within a prefix.
  • At most 100 tasks come in one answer. Send the continuation back, with the same filters, for the next page.

Errors

  • not_found: the project, the parent or the user does not exist.
  • invalid_input: a status or type that is none, or a continuation token that is not valid or belongs to another list.

See also

list_next_tasks for what can start now. get for one task in full.