To filter tasks via the api, you can use a query syntax similar to SQL.
This document is about filtering via the api. To filter in Vikunja's web ui, check out the help text below the filter query input.
Filters in the web UI #
When using filters in Vikunja's web interface, there is an important default setting to be aware of:
"Include Tasks which don't have a value set" is enabled by default. This means a filter like assignees in user1 will also return tasks with no assignee at all. If this is not what you want, disable this toggle in the filter settings.
Saved Filters vs Views #
Vikunja has two related but distinct concepts for organizing how you see tasks:
- Saved Filters are personal, cross-project filter queries. They appear in the sidebar and let you create custom filtered lists across all your projects. Saved Filters cannot be shared with other users.
- Views are per-project display configurations (list, kanban, gantt, table). Each view can have its own filter applied. Views are accessed through the context menu next to the project title (the three dots).
Saved Filters are personal and cannot be shared.
Available fields #
The available fields for filtering include:
done | Whether the task is completed or not |
priority | The priority level of the task (1–5) |
percentDone | The percentage of completion for the task (0–100) |
dueDate | The due date of the task |
startDate | The start date of the task |
endDate | The end date of the task |
doneAt | The date and time when the task was completed |
assignees | The assignees of the task |
labels | The labels associated with the task |
project | The project the task belongs to. Only available for saved filters, not on a project level |
reminders | The reminders of a task. |
created | The time and date when the task was created. |
updated | The time and date when the task was updated. |
All fields are in snake_case when accessed through the api.
You can use date math to set relative dates with any date field. See below for an explanation.
All strings must be either single-word or enclosed in " or '. This extends to date values like 2024-03-11.
Operators #
The available operators for filtering include:
!= | Not equal to |
= | Equal to |
> | Greater than |
>= | Greater than or equal to |
< | Less than |
<= | Less than or equal to |
like | Matches a pattern (using wildcard %) |
in | Matches any value in a comma-separated list of values |
not in | Matches any value not in a comma-separated list of values. Please note this syntax does not work with Typesense, due to limitations in the query language. |
To combine multiple conditions, you can use the following logical operators:
&& | AND operator | matches if all conditions are true |
|| | OR operator | matches if any of the conditions are true |
( and ) | Parentheses | for grouping conditions |
Date Math #
Date Math allows you to specify relative dates which are resolved on the fly by Vikunja when applying the filter.
Each Date Math expression starts with an anchor date, which can either be now, or a date string ending with ||.
This anchor date can optionally be followed by one or more maths expressions, for example:
+1d: Add one day-1d: Subtract one day/d: Round down to the nearest day
These expressions are similar to the ones provided by Grafana and Elasticsearch.
Supported time units #
s | Seconds |
m | Minutes |
h | Hours |
d | Days |
w | Weeks |
M | Months |
y | Years |
Example date math expressions #
now | Right now (Oct 30, 2024, 14:26:12) |
now+24h | In 24h (Oct 31, 2024, 14:26:12) |
now/d | Today at 00:00 (Oct 30, 2024, 00:00:00) |
now/w | The beginning of this week at 00:00 (Oct 27, 2024, 00:00:00) |
now/w+1w | The end of this week (Nov 3, 2024, 00:00:00) |
now+30d | In 30 days (Nov 29, 2024, 00:00:00) |
Oct 30, 2024, 14:26:12||+1M/d | Oct 30, 2024, 14:26:12 plus one month at 00:00 of that day (Nov 30, 2024, 00:00:00) |
Filter Examples #
Here are some examples of filter queries:
priority = 4 | tasks with priority level 4 |
dueDate < now | tasks with a due date in the past |
done = false && priority >= 3 | undone tasks with priority level 3 or higher |
assignees in user1, user2 | tasks assigned to either user1 or user2 |
(priority = 1 || priority = 2) && dueDate <= now | tasks with priority level 1 or 2 and a due date in the past |
When filtering by labels via the API, you must use the label's numeric ID, not its name (e.g. labels in 1, 5). To find a label's ID, use GET /api/v1/labels.