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.
- It
- Reads. It changes nothing.
- Who may call it
- Every user.
- Pages
- Answers in pages of at most 100, with a
continuationtoken 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
| Field | Takes | What it is | |
|---|---|---|---|
project | string | optional | Only events for this project and items it contains. |
parent | string | optional | Only events for tasks contained in this group at any depth, not the group itself. |
text | string 1 to 128 characters | optional | Only events for items whose ID, current title or username contains this text. |
kind | "project" | "task" | "user" | optional | Only events about projects, tasks or users of this kind. |
actor | string 1 to 128 characters | optional | Only events recorded by this user's username or ID. |
action | string 1 to 64 characters | optional | Only 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" | optional | Only 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" | optional | Only status_changed events whose new status is this task or project status. |
from | string | optional | Only events on or after this date or timestamp. |
to | string | optional | Only events on or before this date or timestamp. |
continuation | string | optional | The 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 agent1HTTP
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.
projectlists the changes of the project and of the items it contains now, in nested groups too.parentlists the changes of the tasks a group contains, at any depth, and not the group's own.textfinds items by what their ID, their title as it is now, or their username contains.kindisproject,taskoruser.actortakes a username or a user's ID.actionis one kind of change, such asstatus_changedorlink_added.status_fromandstatus_tokeep only changes of status that left, or arrived at, that status.fromandtobound the time, each as a date or as a moment. A date asfromstarts with that day, and astoends with it.- The
titleis 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
continuationback 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.