Tools in this category
| Tool | Mutating | Description |
|---|---|---|
list_time_goals |
no | Return time goals with their live progress for the current period. Each goal carries achievedSeconds, targetSeconds and the period it is measured over. Default page size 20, max 50. |
get_time_goal |
no | Fetch one time goal by id, with its live progress for the current period. Goals have no display id — use the uuid from list_time_goals. |
create_time_goal |
yes | Create a time goal: a target amount of tracked time over a period, optionally narrowed by any stack of criteria (clients, projects, tasks, time-entry tags, description text). Targets are whole SECONDS, matching how time entries are stored — 40 hours is 144000. |
update_time_goal |
yes | Update a time goal. Only the fields supplied change. Changing recurrence clears the goal’s snapshot and reminder watermarks, so its periods re-derive under the new rhythm. |
pause_time_goal |
yes | Pause a time goal: it stops alerting and reminding and sorts to the bottom of the list. Its history is untouched and its periods still close, so unpausing leaves no gap. Reverse it with unpause_time_goal. |
unpause_time_goal |
yes | Unpause a paused time goal so it alerts and reminds again, and sorts back among the active ones. Pause it with pause_time_goal. |
delete_time_goal |
yes | Delete a time goal and its closed-period history. The history cannot be rebuilt afterwards — the snapshots are the only record of a closed period once the underlying time entries age out. Prefer suspend_time_goal to stop a goal without losing it. |
list_time_goals
Mutating: no
Return time goals with their live progress for the current period. Each goal carries achievedSeconds, targetSeconds and the period it is measured over. Default page size 20, max 50.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
page |
integer | no | Page number (default: 1). |
limit |
integer | no | Items per page (default: 20, max: 50). |
active |
boolean | no | Filter by active flag. Suspended goals are active=false. |
search |
string | no | Search in the goal name |
recurrence |
string (weekly | monthly | one_time) |
no | Filter by recurrence |
clientId |
string | no | Only goals naming this client |
projectId |
string | no | Only goals naming this project |
taskId |
string | no | Only goals naming this task |
tagId |
string | no | Only goals naming this time-entry tag |
sortBy |
string (name | targetSeconds | recurrence | active | startDate | endDate | createdAt | updatedAt) |
no | Field to sort by. |
sortOrder |
string (asc | desc) |
no | Sort direction; applies only when sortBy is set (defaults to asc). With no sortBy, results default to active goals first, then name ascending. |
get_time_goal
Mutating: no
Fetch one time goal by id, with its live progress for the current period. Goals have no display id — use the uuid from list_time_goals.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |
create_time_goal
Mutating: yes
Create a time goal: a target amount of tracked time over a period, optionally narrowed by any stack of criteria (clients, projects, tasks, time-entry tags, description text). Targets are whole SECONDS, matching how time entries are stored — 40 hours is 144000.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Goal name. |
targetSeconds |
number | yes | Target as whole seconds (40 hours = 144000), not hours. |
recurrence |
string (weekly | monthly | one_time) |
yes | weekly and monthly restart with the full target each period; one_time runs between the dates given. |
startDate |
string | no | YYYY-MM-DD. Required for one_time, rejected otherwise. |
endDate |
string | no | YYYY-MM-DD, INCLUSIVE. Required for one_time, rejected otherwise. Max span 366 days. |
criteria |
array | no | What the goal counts. Each entry names ONE thing: {kind:"client",clientId}, {kind:"project",projectId}, {kind:"task",taskId} (counts subtasks too), {kind:"tag",tagId} (the TIME ENTRY's own tags), or {kind:"description",text} (case-insensitive substring of the entry's text). Omit or pass [] for all tracked time. Replaces the whole set on update. |
matchMode |
string (any | all) |
no | any (default) counts an entry matching AT LEAST ONE criterion; all requires every one of them. Below two criteria the modes are identical. |
remindersEnabled |
boolean | no | Email once per period when the deadline is close and the target is unmet. |
reminderLeadDays |
number | no | Fixed lead in days instead of the default last fifth of the period. Ignored unless remindersEnabled. |
reportEmailEnabled |
boolean | no | Include this goal's closed periods in the report email. |
Items of criteria:
kind(string (client|project|task|tag|description))clientId(string)projectId(string)taskId(string)tagId(string)text(string)
update_time_goal
Mutating: yes
Update a time goal. Only the fields supplied change. Changing recurrence clears the goal’s snapshot and reminder watermarks, so its periods re-derive under the new rhythm.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |
name |
string | no | Goal name. |
targetSeconds |
number | no | Target as whole seconds (40 hours = 144000), not hours. |
recurrence |
string (weekly | monthly | one_time) |
no | Switching this clears the period watermarks. |
startDate |
string | no | YYYY-MM-DD. one_time only. |
endDate |
string | no | YYYY-MM-DD, INCLUSIVE. one_time only. |
criteria |
array | no | What the goal counts. Each entry names ONE thing: {kind:"client",clientId}, {kind:"project",projectId}, {kind:"task",taskId} (counts subtasks too), {kind:"tag",tagId} (the TIME ENTRY's own tags), or {kind:"description",text} (case-insensitive substring of the entry's text). Omit or pass [] for all tracked time. Replaces the whole set on update. |
matchMode |
string (any | all) |
no | any (default) counts an entry matching AT LEAST ONE criterion; all requires every one of them. Below two criteria the modes are identical. |
active |
boolean | no | Prefer suspend_time_goal / resume_time_goal, which say what they mean. |
remindersEnabled |
boolean | no | Deadline reminder emails. |
reminderLeadDays |
number | no | Fixed lead in days. Cleared automatically when reminders are switched off. |
reportEmailEnabled |
boolean | no | Include this goal's closed periods in the report email. |
Items of criteria:
kind(string (client|project|task|tag|description))clientId(string)projectId(string)taskId(string)tagId(string)text(string)
pause_time_goal
Mutating: yes
Pause a time goal: it stops alerting and reminding and sorts to the bottom of the list. Its history is untouched and its periods still close, so unpausing leaves no gap. Reverse it with unpause_time_goal.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |
unpause_time_goal
Mutating: yes
Unpause a paused time goal so it alerts and reminds again, and sorts back among the active ones. Pause it with pause_time_goal.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |
delete_time_goal
Mutating: yes
Delete a time goal and its closed-period history. The history cannot be rebuilt afterwards — the snapshots are the only record of a closed period once the underlying time entries age out. Prefer suspend_time_goal to stop a goal without losing it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Time goal ID (uuid). |