Bugzilla:BzAPI:Search

This specific REST API, generally referred to as "BzAPI", is DEPRECATED. For new projects, use the native REST API instead. The BMO team has implemented a compatibility layer to help existing apps transition off BzAPI onto the native REST API. Please migrate existing BzAPI-based apps to the new compatibility-layer endpoint as soon as possible, as BzAPI will be shut off at some point in the future. Direct any questions to the BMO team.

The native REST API is available in Bugzilla 5.0 and up, and on bugzilla.mozilla.org. Although BzAPI is deprecated, it can be used with older Bugzilla installations (versions prior to 5.0) to provide a REST API.

This page defines the URL parameter interface for searching for bugs using the HTTP API (/bug GET). At the moment, the search API call does also support the field names from the web interface, to make it easy to port URLs and other code across. But if supporting this becomes difficult, it might go away.

Note that Bugzilla 4.2 and above limits the number of results returned on an initial search when using the HTML web interface (the default limit is 500). However, this limit does not apply to the interface BzAPI uses - you will always receive all results for your search.

Single Value, Multiplicable

For any single-valued Bug field other than the ones specified below as being special, you can specify any number of individual discrete values as separate URL parameters with identical keys. Multiple values will be ORed together. This includes bug custom fields and (where it makes sense) also works for the field names given in the Boolean Charts section (attachments, comments, flags etc.).

Fields: product, component, severity, priority, etc. etc. etc.

E.g. component=XML&severity=critical&severity=blocker

Note that custom fields must be searched for using their official field names, not the descriptive name from the UI. The official name almost always begins with "cf_". So "cf_blocking_20", not "blocking2.0".

Quick Search

The quicksearch parameter uses QuickSearch syntax.

Text Fields

For the following fields, specify some text to search for. You may also specify a $FIELDNAME_type parameter with a value from the list of types. If you do not, the default is contains_all for keywords, and contains_all_words for everything else.

Fields: comment, keywords, summary, url, whiteboard

E.g. summary=Flash%20crash&summary_type=contains_all_words

The keywords search will complain if your words are not valid keywords.

Person Fields

Specify up to two strings, as email1 and email2, and then specify the fields in which to search for those strings (using booleans such as email1_creator - set to 1 if wanted), and the type of search to do (emailN_type) from the list of types. You can specify multiple email addresses, comma-separated.

Fields: email1, email2, emailN_type, emailN_assigned_to, emailN_qa_contact, emailN_creator, emailN_cc, emailN_comment_creator

E.g. email1=fred@example.com,wilma@example.com&email1_type=equals_any&email1_assigned_to=1&email1_qa_contact=1

Bug ID

Specify id=<comma-separated list>, and an id_mode of either include or exclude (defaults to include). You may instead pass a separate id parameter for each bug ID if you wish. Note that this field does not support aliases.

Deadline

Specify a range with deadline_after and deadline_before. (Note: implementation is actually 'on or before' and 'on or after'; this may change, so be warned).

E.g. deadline_after=2008-02-17&deadline_before=2009-12-31

Changes

You can also ask for bugs that have changed in a particular date range, using changed_after and/or changed_before. If you do, you may additionally specify that a particular field has changed in that time using changed_field, and if you do that, you may also set changed_field_to to specify the new value. If you don't specify a field, it tells you whether the last_change_time is in the range given.

Set "changed_field" to "creation_time" in order to look for bugs filed between certain dates. (It is not possible to do a search which looks for an exact creation time, using a single parameter. If you want to search for an exact creation_time, use Boolean Charts.)

E.g. changed_after=2008-03-31&changed_before=2009-10-31&changed_field=priority&changed_field_to=P1

Boolean Charts

The Bugzilla "boolean charts" mechanism is the way to construct more complex queries, e.g. ones where you want a search type other than a simple "equals".

The parameters for each triple are fieldA-B-C, typeA-B-C and valueA-B-C, where A, B and C are integers beginning at 0.

• A is the number of the chart; each chart is an entirely separate condition on the search.
• Within an A grouping, all charts with the same B are ANDed together.
• Within a B grouping, all charts with the same C are ORed together.

Or, to put it another way, with an example:

0-0-0 && 1-0-0 && (2-0-0 && 2-1-0) && (3-0-0 && (3-1-0 || 3-1-1 || 3-1-2))

Every field on the bug object (except ref, token and work_time, which is Submit Only) can be used with the boolean charts.

A Note on Plurality: some fields on the Bug object whose values are arrays are linguistically plural, but search only applies to a single instance. The field names for search in these cases are in the singular. This applies to: comments, attachments, flags, and groups.

Note that you can't construct a Boolean Chart where the "value" is the empty string. One way to get around this is to use a regex match for "^$".

You may search many attachment fields by specifying a field of "attachment.<fieldname>". The exceptions are creation_time, encoding, the ids, the refs, size and token. Flags on either attachments or bugs are searched for using the same fields below. Additional field values you can use are:

Name	Description
comment.is_private	Comment privacy
comment.author	Person adding a comment
content	Full text of bug; use with special 'matches' type
idle	Time since bug was last changed by anyone, in days (Note: the format of this parameter may change in the future)
flag	Name of a flag (on a bug or attachment)
flag.requestee	Person of whom a flag set is requested (name)
flag.setter	Person who set a flag (name)
assignee_idle	Time since bug was last changed by assignee; postfix number with h/d/w/m/y to specify units (Note: the format of this parameter may change in the future)

Types

The search type values you can use are as follows.

Note that when it says "any of the strings" or "all of the strings", strings are space-separated. So you can't search for a literal string containing a space this way. If you are using multiple parameters, e.g. "component=Foo%20Bar&component=Baz", you get an OR semantic across the parameters by default, even when you use "equals". If you use "contains any of the strings" in that case, because of the space, you'll get every bug in a component whose name contains "Foo", "Bar" or "Baz".

Name	Description	Value Format Notes
equals	is equal to
notequals	is not equal to
equals_any	is equal to any of the strings
contains	contains the string	use 'substring' for search params
not_contains	does not contain the string	use 'notsubstring' for search params
case_contains	contains the string (exact case)
contains_any	contains any of the strings
not_contains_any	contains none of the strings
contains_all	contains all of the strings
contains_any_words	contains any of the words
not_contains_any_words	contains none of the words	use 'nowords' in search params
contains_all_words	contains all of the words
regex	matches regular expression	(As interpreted by DB)
not_regex	does not match regular expression	(As interpreted by DB)
less_than	is less than	Integer or Timestamp
greater_than	is greater than	Integer or Timestamp
changed_before	changed before	Timestamp
changed_after	changed after	Timestamp
changed_from	changed from
changed_to	changed to
changed_by	changed by	name of User
matches	matches	Full text of bug contains the string; use only with special 'content' field
isempty	isempty	Field is empty; "value" is ignored (note: should be 'empty' for consistency, but isn't yet)
isnotempty	isnotempty	Field is not empty; "value" is ignored (note: should be 'not_empty' for consistency, but isn't yet)