MantisHub Query Language (MQL)
MQL is the text form of an issue filter. A query returns the same issues as the filter controls on the Issues page. It covers the same fields. It does not add a separate search syntax on top of those filters.
The Classic UI does not show MQL. Filter setup there is described in Using Filters.
Where you see it
Issues page. Click the eye icon next to the View Issues heading (Show Query). It opens a line of text for the current filter. Click it again (Hide Query) to close the line. With no filter applied, the line reads "No Filter applied".
At the start of that line, the link icon (Copy filter link) copies a View Issues address with ?mql= in it. Opening that address applies the query. Choosing another saved filter, resetting the filter, or saving a filter removes mql from the address, so a reload uses the filter you picked instead.
The line is read-only. It updates when you change the filter with the filter form.
Dashboards. An issue list widget and an issue count widget show the selected filter as MQL while you set the widget up. The text is read-only. Pick a saved filter, or edit the filter with the filter form. How many issues an issue list shows is the widget's Top N value. See Dashboards.
API and AI assistant. The REST API and the MCP server accept MQL. See Use MQL in links and the API.
Shape of a query
<field> <operator> <value> [AND|OR more conditions] [ORDER BY ...] [LIMIT n]AND means every condition must match. OR means any condition may match, and it applies to the whole query. A query is all AND or all OR. Mixing them is rejected.
To match any of several values on one field, use a list:
status = [resolved, closed]
priority = [high, urgent]AND, OR, ORDER, and LIMIT are recognized in any letter case. Field names, function names, and the names of enumeration values are case-sensitive.
Each field may appear once. A date field (created_at, updated_at, or a date custom field) may appear twice, which is how you write a range. A query may be at most 6000 characters.
Spaces around = are optional, so status=resolved is the same as status = resolved.
Fields and operators
| Field | Operators | Values |
|---|---|---|
assignee, reporter, follower, commenter | = | A username, a list of usernames, user() (you), none() (nobody), or any(). |
project | = | A project name, a project id, a list, or project() for the current project. |
status, priority, severity, resolution, projection, view_state | =, !=, <, <=, >, >= | A name, an id, or a list. = and != accept a list, for example status != [closed, new]. <, <=, >, and >= take a single value and use the order of the ids, not alphabetical order. |
category, version, fixed_in_version, target_version, tags | = | A name, an id, or a list. |
build, platform, os, os_build | = | A name or a list of names. Quote a name that is all digits, for example build = "1234". |
profile | = | A profile id only. Names are rejected because they are not unique. |
sticky | = | true, false, 1, or 0, in any case. |
created_at, updated_at | =, <, <=, >, >= | A date. See Dates. |
search | — | A call: search("login error"). See Short forms. |
relationship | — | A call such as duplicateOf(123). See Short forms. |
Custom fields: cf["Field Name"] or cf[id] | =. Date custom fields also take <, <=, >, >=. | A value of that field. See Custom fields. |
Any other operator is an error. For example, category != Bugs gives Invalid operator: != for field: category.
These names are filter fields only. id, summary, and description are not. To find words in the summary, description, or notes, use search("...").
A user name that does not exist, or a project name that does not exist or that you cannot see, is an error. Use user() for yourself. A custom field that does not exist is ignored, as described under Custom fields.
Enumeration fields
Enumeration fields have a fixed list of values: status, priority, severity, resolution, projection, and view_state. Each value has a name, such as resolved, and an id/code, such as 80.
Names and ids come from your instance. Custom statuses work when they are configured. The usual starting set is:
- Status:
new,feedback,acknowledged,confirmed,assigned,resolved,closed - Priority:
none,low,normal,high,urgent,immediate - Severity:
feature,trivial,text,tweak,minor,major,crash,block - Resolution:
open,fixed,reopened,unable to duplicate,not fixable,duplicate,not a bug,suspended,wont fix - Projection:
none,tweak,minor fix,major rework,redesign - View state:
public,private
priority = none is the priority named none. It is not the same as none(), which means "no value" on fields such as assignee.
A name that contains a space must be quoted: resolution = "unable to duplicate". The text shown in the UI, including translated text (for example a translated word for "resolved"), is not accepted. Use the name or the id: status = resolved and status = 80 are the same thing when 80 is the id of that status on your instance.
statusResolved() and statusClosed() are the resolved and closed thresholds from your configuration. Use them instead of writing resolved or closed. If an administrator changes the status list, they still point to the right status.
status < statusResolved()
status >= statusClosed()Custom fields
cf["Tier"] = Gold
cf[21] = GoldThe name inside the quotes must match the field definition, including case and spaces. A name that contains " or \ cannot be written that way. Use the numeric id: cf[21].
A date custom field takes =, <, <=, >, >=, and may appear twice for a range. Every other custom field type takes = only. != is rejected for all custom fields.
If the name or id does not exist, that condition is left out and the rest of the query still runs. A typo in the name returns more issues than you asked for, with no error. Copy the name from the field definition.
Short forms
search and the relationship names are a whole condition. The older field = ... spelling still works and means the same thing. Queries that MantisHub generates use the short form.
search("login error")
duplicateOf(123)
childOf(*)
relationship = none()search("login error") is one search term. It uses the same text search as the search box on the Issues page, across the summary, the description, and the notes. search() with no term, or with two terms, is an error. search("") adds no text filter.
| Call | Matches |
|---|---|
parentOf(123) | Issues that are the parent of issue 123 |
childOf(123) | Issues that are a child of issue 123 |
duplicateOf(123) | Issues marked as a duplicate of issue 123 |
hasDuplicate(123) | Issues that have issue 123 as a duplicate |
relatedTo(123) | Issues related to issue 123 |
linkedTo(123) | Issues with any relationship to issue 123 |
notLinkedTo(123) | Issues that are not related to issue 123, including issues with no relationships |
relationship = none() | Issues with no relationships |
For parentOf, childOf, duplicateOf, hasDuplicate, and relatedTo, the id is optional. childOf(*) and childOf() both mean "a child of any issue". Queries that MantisHub generates use the * form. * is allowed only as that argument.
linkedTo and notLinkedTo require an id. none() and any() take no argument, and they stay attached to the field: relationship = none(), assignee = none().
An id is a positive whole number. Leading zeros are fine (duplicateOf(000123)). 0, negatives, and fractions are rejected. A call with an extra argument, such as childOf(1, 2), is rejected.
relationship = any() is accepted and then dropped, because leaving the field out already means "any".
Dates
Dates are calendar days. Times of day are ignored.
Three ways to write a date, on created_at, updated_at, or a date custom field:
created_at >= 2026-01-01
updated_at >= -7d
created_at >= startOfMonth()A fixed date is YYYY-MM-DD or YYYY/MM/DD. Words such as tomorrow or next Monday are rejected.
A relative offset is one number and one unit, and quotes are not needed: d days, w weeks, m months, y years. A leading - is in the past. No sign, or +, is in the future. -7d is seven days ago. 1w is one week from today. 1w 2d is not valid.
A date function is today(), startOfMonth(), endOfMonth(), startOfYear(), or endOfYear(). Each may take one offset:
created_at >= startOfMonth(-10d)
updated_at >= startOfYear(-1y)
created_at >= startOfMonth(-1)With no unit, the offset uses the function's own period, so startOfMonth(-1) is the start of last month and today(-1) is yesterday. An offset in a different unit moves the date: endOfMonth(-10d) is ten days before this month ends. today(-7d) and -7d are the same day. -7d is the shorter way to write it.
today(-7d) and today("-7d") are the same call. 2026-01-01 + 15d is a syntax error. There is no date() function.
A month or year step that would pass the end of the target month stays on the last day of that month. On 31 December, endOfYear(-1m) is 30 November.
When the date is set. A relative offset or a date function becomes a fixed date when the query runs. After that, it does not move. Show Query shows the fixed date, and Copy filter link and a saved filter keep it. For example, on 13 November 2026, updated_at >= -7d shows as updated_at >= 2026-11-06. A filter saved from it still starts on 6 November a week later. A ?mql= link that you write yourself with -7d in it is worked out again each time you open it.
> and < leave out the day you name. created_at > 2026-01-01 starts on 2 January. created_at < 2026-01-01 stops on 31 December of the previous year. =, >=, and <= include the day. created_at = 2026-01-01 is that day only.
A range is two conditions:
created_at >= 2026-01-01 AND created_at <= 2026-03-31
cf["Due"] >= today() AND cf["Due"] <= 30dcf["Due"] = none() matches issues where that date is unset. On any field that is not a date, a date-shaped value is ordinary text: version = 7d is the version named 7d.
Quoting
Double quotes and single quotes are the same.
A value needs no quotes when it contains only letters, digits, and _ . - / @ +.
status = resolved
build = release-1.0
assignee = alex.smith
category = "a,b"
cf["Load"] = "50%"Quote a value that contains a space, or %, ,, :, #, &, brackets, or an operator character. Quote and, or, order, and limit when they are the value itself: category = "and".
Inside double quotes, \" is a quote. Inside single quotes, \' is a quote. \\ is a backslash in either. Any other backslash is kept as written.
A bare whole number is an id. A quoted number is a name.
category = 29
category = "29"The first is the category whose id is 29. The second is the category named 29.
Parentheses make a function call only when the name is unquoted.
assignee = user()
assignee = user
assignee = "user()"The first is you. The second is a user named user. The third is a user named user(). On a text field or a user field, forgetting () is not a syntax error. The query filters on that name. On a status or a date, the bare name fails because it is not a valid value: write statusResolved() and today().
today(), none(), and statusResolved() on their own are errors. They need a field: created_at >= today(), status < statusResolved(). A field written as a call is also an error: status(open) should be status = open.
What a query includes by default
A condition you leave out is not a blank. It uses the same defaults as the Issues page:
- Status. With no status condition, statuses at or above the hidden-status setting are omitted. Out of the box that setting is closed, so closed issues are hidden. Writing a status yourself replaces that default.
status = [resolved, closed]returns those statuses.status = any()returns every status, including closed. - Project. The current project, unless the query has a
projectcondition, for exampleproject = Website. - Sort. Last updated, newest first, unless you write
ORDER BY. - Page size. The instance default (50 unless an administrator changed it), unless
LIMITor the APIpage_sizesays otherwise. See below.
ORDER BY and LIMIT
ORDER BY priority DESC
ORDER BY updated_at DESC, id DESC
priority = high ORDER BY priority ASC LIMIT 25ORDER BY and LIMIT go at the end of the query, after conditions such as priority = high. Each may appear once. They may be in either order.
Direction defaults to DESC. Say ASC when you want ascending. At most two sort fields are allowed. When two dates can tie, add id as the second field so paging stays stable.
A sort name is a bare word: letters, digits, _, and .. These filter fields also sort: project, status, priority, severity, resolution, projection, category, created_at, updated_at, os, os_build, platform, version, fixed_in_version, target_version, build, view_state, assignee, reporter.
id and summary sort and do not filter. reproducibility sorts the same way. eta, due_date, overdue, and sponsorship_total sort only when that feature is enabled for you. os, os_build, platform, projection, and build depend on instance settings too, so a sort that works on one instance can be rejected on another.
These do not sort: search, relationship, follower, commenter, sticky, profile, tags, description, notes, steps_to_reproduce, additional_information, attachment_count, and bugnotes_count.
Older column names still parse: date_submitted, last_updated, handler_id, reporter_id, project_id, category_id. Prefer created_at, updated_at, assignee, reporter, project, and category.
A custom field sorts by its column name, custom_ plus the field name, and only when that name has no spaces:
priority = high ORDER BY custom_Tier ASCORDER BY cf["Tier"] and ORDER BY cf[21] are syntax errors. A name that contains a space cannot be written as a sort field. Filter on that custom field and sort on a normal field instead.
LIMIT is a positive whole number, at least 1. A value above 100 is capped at 100.
ORDER BY updated_at DESC LIMIT 10Who uses that number depends on the caller:
- The REST
issues_listroute readspage_sizefrom the request body, not fromLIMITinside the query, so it ignoresLIMIT. The size is capped at 100. Withoutpage_size, the instance default applies. See Use MQL in links and the API. - The AI assistant's issue search reads
LIMITfrom the query and sends it aspage_size. If you pass both,page_sizewins. - On the Issues page, move between pages with the list controls. Dashboard issue lists use the widget's Top N setting for how many rows to show.
Use MQL in links and the API
Links
Copy filter link on the Issues page builds a View Issues address for the project, with the query in mql:
https://yourmantishubname.mantishub.io/projects/1/issues?mql=status%20%3D%20%5Bnew%2C%20assigned%5D%20AND%20priority%20%3D%20highThe query must be percent-encoded, as in the example. Opening the address applies the query. A relative date such as -7d in a link you write yourself is worked out again each time the link is opened.
REST API
The ApiX endpoints take a filter object. For MQL, set "type": "mql" and put the query in query. Requests use Authorization: Bearer with your API token.
List issues. POST /api/rest/plugins/ApiX/issues_list
curl -X POST \
-H "Authorization: Bearer replace-with-user-API-token" \
-H "Content-Type: application/json" \
"https://yourmantishubname.mantishub.io/api/rest/plugins/ApiX/issues_list?describe=1" \
-d '{
"project": { "id": 1 },
"filter": { "type": "mql", "query": "assignee = user() AND status < statusResolved() ORDER BY priority DESC" },
"page": 1,
"page_size": 25
}'projectis an object withid. Omit it to search all projects.page_sizein the body sets the page size, up to 100. This endpoint ignoresLIMITin the query.describe=1adds adescriptionfield with the filter as MQL text.
Convert a filter to MQL. POST /api/rest/plugins/ApiX/projects/{project_id}/filters/mql returns the MQL text for a filter without running it. The filter object takes "type": "saved" or "standard" with an id, "type": "custom" with criteria, or "type": "mql", which is returned unchanged.
curl -X POST \
-H "Authorization: Bearer replace-with-user-API-token" \
-H "Content-Type: application/json" \
"https://yourmantishubname.mantishub.io/api/rest/plugins/ApiX/projects/1/filters/mql" \
-d '{ "filter": { "type": "saved", "id": 12 } }'The response is {"type": "mql", "query": "..."}.
The full list of ApiX operations is in the API reference. Both endpoints are marked beta there.
Common errors
The message names the problem. A syntax error also shows a short snippet of the query. A value error (a bad status, a bad date, mixed AND and OR) does not.
| You wrote | What to do |
|---|---|
Unknown field, such as assignedto | Use a name from the table above. Invalid MQL field: assignedto |
status high | Put an operator in. Expected a valid operator after field 'status'. |
status(open) | status is a field. Write status = open. |
today() with no field | Write created_at >= today(). Function 'today' cannot stand alone |
search() or search("a", "b") | search takes exactly one term: search("login error"). |
priority = high AND status = new OR severity = crash | Use only AND or only OR. |
priority = high AND priority = urgent | Use a list: priority = [high, urgent]. Duplicate field 'priority' is not allowed |
created_at >= -30d AND created_at <= today() AND created_at >= -7d | A date field may appear twice. supports at most 2 clauses |
priority >= [high, urgent] | A comparison takes one value. != and = are the operators that take a list. |
created_at != today() or cf["Tier"] != Gold | != is only for enumeration fields. |
version = today() | Date functions belong on date fields. |
status = neww | The message lists the names your instance accepts. |
assignee = nobody | There is no user named nobody. User 'nobody' not found. Use an existing username, or user(). |
project = Nope | No project you can see has that name. Project 'Nope' not found or not accessible. Use a project name or id you can see. |
created_at >= tomorrow or created_at >= 7dd | Use YYYY-MM-DD, a relative offset such as 7d, or today(). |
ORDER BY id, priority, severity | Two sort fields maximum. |
ORDER BY search or ORDER BY cf["Tier"] | search is not a column. Custom fields use custom_Tier, and only when the name has no spaces. |
LIMIT 0 | LIMIT value must be at least 1. |
| A query longer than 6000 characters | Shorten it. MQL query exceeds maximum length |
Examples
Assigned to you, still unresolved, highest priority first:
assignee = user() AND status < statusResolved() ORDER BY priority DESC, id DESCUnassigned, high or urgent:
assignee = none() AND priority = [high, urgent]Text search over the last two weeks:
search("login error") AND updated_at >= -14d ORDER BY updated_at DESCOpened this month, including issues that are already closed. status = any() is required, because a query with no status hides closed issues:
created_at >= startOfMonth() AND status = any()Duplicates of issue 123, including closed ones:
duplicateOf(123) AND status = any()A custom field and a due-date window, ten rows:
cf["Tier"] = Gold AND cf["Due"] >= today() AND cf["Due"] <= 30d ORDER BY updated_at DESC LIMIT 10Reported by a teammate, in one project:
project = "Website" AND reporter = alex AND created_at >= startOfYear()