Query endpoint

You can manipulate data sources through the use of queries, which are commands piped one after another.

See Queries, or go to /#/query in your Nozomi Networks solution Web user interface (UI) for examples.

Requirements and restrictions

  • Users must have permission to execute application programming interface (API) calls
  • Results display the list of queried items
  • We recommend that you use pagination, adding page and count params
  • The page param is the page number to return, and count is the page dimension
  • If count is not provided, the default value is 10,000; if page is not provided, the default page number is 1
  • If the provided count value is higher than 10,000, no more than 10,000 items are returned
  • The maximum allowable page number is 1,000. Requests for pages beyond this limit will result in an error response Bad request

Example: To see how many nodes are in the system, call the following uniform resource locator (URL): https://10.0.1.10/api/open/query/do?query=nodes | count

Figure 1. Example of a count query

Example of a count query

A more complex example is: https://10.0.1.10/api/open/query/do?query=nodes | where_link protocol == http | head 5.

In the image we've used Postman's interface to collapse the results so you could clearly see it's five, as we wanted.

Figure 2. Filtering HTTP and taking the first five results

Filtering HTTP and taking the first five results

HTTP API Best Practices

Use time filter for ordering and filtering

When fetching items from the API, consider using a time filter, such as record_created_at, to sort the items and retrieve only those that are greater than the specified time value. This allows efficient fetching of recent data.

alerts | sort record_created_at asc | where record_created_at > 1674828173887

Handling page 1000 number limit

The API supports pagination with a page parameter; it is advisable to set up a time field pivot when reaching page 1000 and start again from page 1.

/api/open/query/do?query=alerts | sort record_created_at asc | where record_created_at > 1674828173887&page=1&count=100

Select only relevant fields

When making API requests, specify the fields you are interested in. This will ensure that the API response contains only the data that is relevant to your use case, reducing the size of the response payload and minimizing unnecessary data transfer.

alerts | select id risk record_created_at description name

Limit items per page

To avoid heavy response payloads and potential performance issues, it is recommended to set a reasonable limit on the number of items per page. Generally, the number of items per page should be kept below 1000, unless there is a specific use case that necessitates a higher value.