Searching: simple search#
Simple search is using the
GET method, and is accepting a set of basic query
parameters for filtering, sorting, and limit/offset.
Filtering parameters are appended as query parameters, e.g.
GET /assets/v1/host?customerID=1 will search for host assets for customer
Many filtering parameters accept multiple values, the default behaviour
is to search for any of the provided values, e.g.
will search for host assets for customer
Combining different search criteria generally has an AND logic, e.g.
GET /assets/v1/host?customerID=1&keywords=myhost will mean to search for hosts for
1 which also matches the keyword
See API documentation for valid filtering parameters.
Limit, offset and sorting#
By default, any endpoint has a default limit of 25 elements : search endpoints (simple
or advanced) will generally limit output to 25 rows, but allows user to override
to get more/fewer rows, and set an
offset to perform pagination.
The query parameters
offsetcan be added to override the
limit=0, the endpoint will perform an unlimited search, up to the
system-defined maximum limit.
If the user sets a limit above the maximum limit, the endpoint will return an argument error.
If the user requests an unlimited search, which would return more than
the system defined maximum limit, the endpoint will return
Currently, the system defined maximum result limit is
offset=X, the endpoint will return the number of results
limit, after skipping the first
Endpoints have a default sort order. To change the sorting, endpoints have a
parameter, which allows changing the default sort property and direction, e.g.
will sort by ID ascending, while
sortBy=-id will sort by ID descending.
sortBy parameters will define a chained sorting order, e.g.
sortBy=timestamp&sortBy=id will sort all entities by timestamp first, then by ID.
See API documentation for valid sorting parameters.
limit=10will return the first 10 results (as defined by the default sort order)
limit=10&offset=10will return the next 10 results after the 10 first results (as defined by the default sort order)
limit=10&sortBy=timestampwill return the first 10 results when ordered by timestamp
limit=0will return all available results. If the requested search would return more than the system-defined limit, this will return an argument error.
If fetching large amounts of data, using pagination can help speed up the process by conserving both client and system resources, and will give quicker response times.
By performing an initial search with a “moderate limit” (e.g. 1000 rows), the returned
count allows the client to determine how much data there is to fetch, and paginate through it.
may return :
Then, the client can perform 19 additional
GEToperations to fetch the rest: