List computers
GET/computers
Returns the computers (managed systems) in the inventory, one page at a time.
Required role: superadmin, admin or user. When the "my systems" release toggle is on, a plain user in advanced mode sees only the systems that user can administer.
There are three query modes, chosen by the query string:
- IP lookup (
ippresent). The server queues a DNS lookup job, waits for a worker to finish it, records the address as the computer'slast_ip, then returns the computers whosecnandlast_ipstart with the resolved values (case-insensitive prefix match). If no host name resolves, the response is an empty array. - Advanced (
advancedpresent and notfalse). Filters accept operators,selectpicks fields, andretiredswitches the collection that is searched. - Standard (neither). Any other query parameter filters on a computer field as a case-insensitive starts-with match (
true/falsematch booleans; send plain values). Operators andselectare not available. An unknown field returns 400.
Any query parameter that is not reserved (page, limit, sort, inlinePageInfo, advanced, select, retired, ip) is a filter on the field of the same name, using dot notation for nested fields (for example policy.scan=true, os_type=linux, config.directory_bridging.strategy=sssd). Any computer field that is not hidden can be filtered (dot notation for nested fields). Hidden fields, such as objectGUID, and non-string values return 400. Repeat a key as field[]=a&field[]=b for an in-list match.
Advanced operators (value prefixes, advanced mode only; ^, $ and ~ match case-insensitively; equals, not-equal and in-list are exact, case-sensitive matches):
| Prefix | Meaning | Example |
|---|---|---|
| (none) | equals | cn=WEB01 |
! | not equal | os_type=!windows |
| (empty value) | field exists | last_ip= |
! alone | field does not exist | last_ip=! |
> >= < <= | number or date comparison | lastLogonTimestamp=>2026-01-01 |
^ | starts with | cn=^WEB |
$ | ends with | cn=$01 |
~ | contains | cn=~eb0 |
field[]=a&field[]=b | in list | os_type[]=linux&os_type[]=macos |
field[]=!a&field[]=!b | not in list | os_type[]=!linux |
Values are converted using the field type (string, number, boolean, date). Date fields also accept relative times such as <=now-30d.
Default fields in a list response: config, objectGUID, distinguishedName, cn, objectSid, domain_fqdn, domain_netbios, operatingSystem, policy, dNSHostName, last_ip, last_scanned, lastLogonTimestamp, lastScan, os_type. In advanced mode select can also name admins.current.
Paging: limit, page and sort apply in every mode. Add inlinePageInfo to wrap the array as {limit, page, pages, total, links, docs}. Out-of-range paging values are not rejected: a limit of 0, a negative limit or a non-numeric limit returns an empty array (X-Pagination-Max-Count: 0); a limit above 1000 is capped at 1000; a page below 1 or non-numeric is treated as page 1; a page past the end returns an empty array; a sort on an unknown field is ignored.
Query errors: in advanced mode an unknown select field or a field that cannot be selected, returns 500 rather than 400; send only fields that exist and can be returned. A filter on an unknown field returns 400 InvalidQuery.
Request
Responses
- 200
- 400
- 401
- 403
- 408
- 422
- 500
A page of computers. Paging metadata is in the X-Pagination-* and Link headers. In advanced mode X-Pagination-Count carries the requested page size rather than the number of rows returned, and X-Pagination-Max-Count is not sent; standard mode sends both correctly.
Response Headers
Number of records in this page.
Page size used for the request (limit).
Current page number.
Total number of pages.
Total number of records matching the query.
RFC 8288 links with rel values first, last, and, when they exist, prev and next.
Unknown filter field or invalid query value.
No token, or the token is invalid or expired. The body is {message}: No auth token provided when no token is sent, otherwise the token check's message (jwt expired, jwt malformed, invalid signature, invalid token, jwt signature is required). Send Authorization: Bearer <token> exactly: the server drops the first seven characters of the header and reads the rest as the token, so a different scheme or an extra space fails. If Authorization is absent, the server reads a token field in the body, then a token query parameter, then x-access-token. Routes that validate query fields reject ?token= with 400 InvalidQuery.
The token's role is not allowed for this operation, or the token's scopes exclude the route
(Scope not allowed by token).
The IP lookup (ip mode) did not finish in time. Body is a typed error with name TimeoutError.
The request could not be processed, for example an id that is not a valid object id.
The query could not be run (for example select in advanced mode names an unknown field or a field that cannot be selected) or an unexpected error occurred. Send a valid select.