Collection Filtering

When querying collections, filters can be specified by providing one or more filter[]=…​ parameter.

GET /api/:collection?filter[]=...&filter[]=...&filter[]=...

Syntax for a filter is as follows:

filter[]=attribute op value

By default, filters are logically anded together, for a logical or, prefix the attribute with or as follows:

filter[]=or attribute op value

Where op supports the following operators:

Operator Description Operands



Numeric or string. For String, supports % or * as wildcard

NULL or nil can also be specified instead of quoted string




Less Than



Less Than or Equal



Greater Than or Equal



Greater Than


When strings, value to be quoted in single or double quotes. When datetimes, only strict comparison operators are supported.

Example Query VMs named sample*, created_on > 2019-09-01, and return name and vendor

GET /api/vms?expand=resources&attributes=name,vendor&filter[]=created_on>2019-09-01&filter[]=name='sample%'

Example Query looking for services that are retired but have an unspecified service_id

GET /api/services?expand=resources&attributes=retired&filter[]=service_id=nil&filter[]=retired=true

Attributes specified via the filter[] parameter can include virtual attributes, including one level association of the virtual attribute as follows:

The HTTP OPTIONS request can be used on a collection to display all of the collection specific metadata, including the available virtual attributes. For more information please refer to the Collection Metadata page.

GET /api/vms?attributes=name,vendor,hardware&filter[]=vendor='vmware'&filter[]=hardware.memory_mb>=8192

Here filtering on the virtual attribute hardware including the one level association memory_mb off hardware.