list_timesheets
Lists timesheets, newest week first, for a project or for the person the token acts as, with each week's tallies and where it stands between open, awaiting approval and approved.
Read where the weeks stand before you report on them or put one forward. A timesheet is one person's week of time on one project, Monday to Sunday: give project_id for a project's weeks, or leave it out for the weeks of the person the token acts as across the projects it may see. Each row carries week_start and week_end, the total_minutes the week holds with billable_minutes among them and the same in words, entry_count, the status (open while the logs still change, submitted while an approver reads them and the logs hold, approved once they are locked), held, who approved or reopened it and when, and its approved version. Narrow with user_id, status, week_start (any day of the week), from and to (Mondays); page with limit and page. A client guest's token reads none.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same actions as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_idstringoptionalUUID of a project, for its weeks; leave it out for the weeks of the person the token acts as.
user_idstringoptionalNarrow to one person's weeks.
statusstringoptionalNarrow to one state.
opensubmittedapprovedweek_startstringoptionalOne week, by any of its days, Y-m-d.
fromstringoptionalThe first week to include, by its Monday, Y-m-d.
tostringoptionalThe last week to include, by its Monday, Y-m-d.
limitintegeroptionalRows per page, 1 to 100; 50 by default.
pageintegeroptionalThe page, from 1.
What it returns
{ "data": [ { "id": "4a5b6c7d-8e9f-4a1b-8c2d-3e4f5a6b7c8d", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "project_key": "CRM", "project_name": "Customer Portal", "user_id": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b", "user_name": "Dev Lead", "week_start": "2026-11-02", "week_end": "2026-11-08", "status": "submitted", "held": true, "total_minutes": 2280, "total_duration": "38h", "billable_minutes": 1800, "billable_duration": "30h", "entry_count": 12, "submitted_at": "2026-11-08T17:30:00+00:00", "returned_at": null, "approved_by": null, "approver_name": null, "approved_at": null, "reopened_at": null, "reopened_by": null, "version": 0, "created_at": "2026-11-08T17:30:00+00:00", "updated_at": "2026-11-08T17:30:00+00:00" } ], "meta": { "page": 1, "per_page": 50, "total": 1, "last_page": 1 }}How it fails
VALIDATION_FAILEDan unknown status.
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope.
FORBIDDENthe holder's role on the project does not carry time-log:view-any, or the token is a client guest's.
TOKEN_MISSING_ABILITYtoken lacks time-log:view-any.
How is this guide?
Last updated on