ticktick_filter_tasks
Filter TickTick tasks by project, priority, tag, status, and due or completion date range in one query; return matching open or completed tasks as compact or full JSON results.
Instructions
Return the tasks matching every supplied filter criterion.
Supports any combination of project, priority, tag, status, and a date window applied to either the due date (open tasks) or the completion timestamp (completed tasks).
Args:
detail (str, optional): "compact" (default) or "full".
Compact drops the heavy content/desc/checklist
items blobs and bulky sync metadata, keeping id,
projectId, title, dueDate, startDate, priority, status,
isAllDay, timeZone, tags plus a contentPreview (first
~200 chars of content) so keyword search still works. Full
returns the raw task objects unchanged. To edit a task, call
ticktick_update_task with its id and only the fields to
change, plus projectId for a completed task.
filter_criteria (dict | str): A criteria object, or a JSON string
that decodes to one. No value below reaches the query
unchecked, and any key not on this list is an error rather
than something ignored, so a mistyped key fails loudly.
Recognised keys:
* ``status``: ``"uncompleted"`` (default) or ``"completed"``.
When ``"completed"`` you should supply
``completion_start_date`` and/or ``completion_end_date``;
without dates the result is an empty list.
* ``project_id`` (str): Limit to tasks in this project.
Accepts the project's name as well as its ID
(case-insensitive, trimmed). Two projects sharing a
name is an error, not a guess, and so is a project the
account does not have.
* ``priority`` (int): 0=None, 1=Low, 3=Medium, 5=High. Must be
a JSON integer; the string ``"3"`` and the float ``3.0`` are
errors, as is any other value.
* ``tag_label`` (str): Tag name (case-sensitive), non-empty.
Surrounding whitespace is trimmed.
* ``due_start_date`` / ``due_end_date`` (str): ISO date or
datetime strings; only used when ``status='uncompleted'``.
A value that cannot be read as a date is an error, so a
window is never silently dropped, and a window that ends
before it begins is an error too. Bounds apply at day
granularity, so any time part is ignored rather than
validated.
* ``completion_start_date`` / ``completion_end_date`` (str):
ISO date or datetime strings; only used when
``status='completed'``. Same date rules as above.
* ``tz`` (str): Default IANA timezone applied to date filters,
e.g. ``"Europe/London"``. A name that does not resolve is an
error rather than being ignored, so results are never
labelled with a zone that was not applied.
* ``sort_by_priority`` (bool): Sort by descending priority.
Must be a JSON boolean; the strings ``"true"``/``"false"``
and ``1``/``0`` are errors.Returns:
JSON list of matching task objects (compact by default; see
detail). Empty list if nothing matches. If a compact result
would still exceed the size budget, the soonest-due matches are
returned and a final _truncation_note element reports how
many were omitted -- nothing is dropped silently. On invalid
input or backend failure: {"error": "...", "status": "error"}.
One error carries an extra key: outcome: "project_list_unverifiable" means the project list could not be
refreshed to confirm project_id, so retry rather than
concluding the project is gone.
Freshness:
Uncompleted queries read local state, synced from the server at most
once per throttle window (default 15s,
TICKTICK_MCP_SYNC_TTL_SECONDS); a change made elsewhere within
that window may not be visible yet -- call ticktick_sync to force
a refresh. Completed queries are always fetched live.
Limitations:
- TickTick caps get_completed at 100 results; very wide
completion windows are truncated server-side.
- Filtering happens client-side after the fetch, so additional
criteria do not reduce the number of network requests.
- Compact output is for browsing only; full content for one task
is available via ticktick_get_by_id or detail="full".
Agent Usage Guide:
- List open tasks in a project:
{"status": "uncompleted", "project_id": "<id>"}
- List completed tasks in the last 7 days:
{ "status": "completed", "project_id": "<id>", "completion_start_date": "2026-05-21", "completion_end_date": "2026-05-28" }
- Find high-priority open tasks due this month, sorted:
{ "priority": 5, "due_start_date": "2026-05-01", "due_end_date": "2026-05-31", "sort_by_priority": true }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | compact | |
| filter_criteria | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |