Vigile
SearchContents

DocumentationOperations

list_history

List retained changes across the plan, newest first. Filter by project, group, item ID, current title or username, item kind, actor, action, previous or new task/project status, or time range. A project includes events for items it currently contains, including items in nested groups. A group includes events for tasks it contains at any depth, not the group's own events. Each entry names its item, actor, action and data, and task completion events include elapsed wall-clock duration from creation. Returns at most 100 per call; pass the continuation token unchanged with the same filters to read older changes.

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
Recorded changes across the plan, newest first.
MCP tool
list_history
HTTP
POST /api/list-history
Command
vigile list-history

Input

FieldTakesWhat it is
projectstringoptionalOnly events for this project and items it contains.
parentstringoptionalOnly events for tasks contained in this group at any depth, not the group itself.
textstring
1 to 128 characters
optionalOnly events for items whose ID, current title or username contains this text.
kind"project" | "task" | "user"optionalOnly events about projects, tasks or users of this kind.
actorstring
1 to 128 characters
optionalOnly events recorded by this user's username or ID.
actionstring
1 to 64 characters
optionalOnly this kind of event, such as status_changed or link_added.
status_from"draft" | "open" | "in_progress" | "paused" | "in_review" | "done" | "cancelled" | "in_preview" | "ready" | "broken"optionalOnly status_changed events whose previous status is this task or project status.
status_to"draft" | "open" | "in_progress" | "paused" | "in_review" | "done" | "cancelled" | "in_preview" | "ready" | "broken"optionalOnly status_changed events whose new status is this task or project status.
fromstringoptionalOnly events on or after this date or timestamp.
tostringoptionalOnly events on or before this date or timestamp.
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-history --project WEB --action status_changed --as agent1

HTTP

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

MCP tool call

{
  "name": "list_history",
  "arguments": { "project": "WEB", "action": "status_changed" }
}

The answer

{
  "changes": [
    {
      "kind": "task",
      "id": "WEB-014",
      "title": "Staging site is down after the last deploy",
      "at": "2026-03-02T13:22:00.000Z",
      "by": "agent1",
      "action": "status_changed",
      "data": { "from": "open", "to": "in_progress", "assigned_to": "agent1" },
      "place": [35, 0]
    },
    {
      "kind": "task",
      "id": "WEB-011",
      "title": "Import customer accounts from the old shop",
      "at": "2026-03-02T13:08:00.000Z",
      "by": "agent2",
      "action": "status_changed",
      "data": { "from": "open", "to": "in_progress", "assigned_to": "agent2" },
      "place": [34, 0]
    }
  ]
}

This is what a service answered when this page was built; for the page, changes shows 2 of 12. 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

changes: the recorded changes across the plan, newest first. Each one names its item by kind, id and title, and says at what moment, by whom, the action and its data. A change that completed a task also carries duration_ms: the time from the task's creation to that completion. place is the change's position in the plan's history. A continuation token is there when older changes follow.

Rules

  • The filters narrow together: a change is listed when it fits all that are given.
  • project lists the changes of the project and of the items it contains now, in nested groups too. parent lists the changes of the tasks a group contains, at any depth, and not the group's own.
  • text finds items by what their ID, their title as it is now, or their username contains.
  • kind is project, task or user. actor takes a username or a user's ID. action is one kind of change, such as status_changed or link_added.
  • status_from and status_to keep only changes of status that left, or arrived at, that status.
  • from and to bound the time, each as a date or as a moment. A date as from starts with that day, and as to ends with it.
  • The title is the item's title now, not the one it had then. The changes of an item that was deleted for good are not listed: its history went with it.
  • At most 100 changes come in one answer. Send the continuation back unchanged, with the same filters, for the older ones.

Errors

  • not_found: the project, the parent or the actor does not exist.
  • invalid_input: a kind or status that is none, a date that is none, a range that ends before it starts, or a continuation token that is not valid or belongs to another list.

See also

get with history reads the changes of one item, and its status timeline. Versions and history says what is recorded.