Index


Overview

Filters are a core component of working effectively with the Statseeker RESTful API. Filters can be applied to specify which resources (devices, interfaces, groups etc.) to report on, and can also be applied to specify a time-range for data collection and reporting.

Filters can be specifically applied by entering a filter statement, and/or by proxy through a combination of limit and {field}_sort keys.

Some examples provided in this document contain API queries that have been URL encoded, removing non-essential spaces, replacing essential spaces and special characters with the appropriate ASCII character.

[top]


Filtering Using Limit and Sort

All Statseeker API GET requests can contain both limit and {field}_sort keys. In combination these keys can be used to filter the contents of the response from the API.

The limit key is primarily included for use in pagination of the response in conjunction with the offset key (see Pagination for details), and can be employed to place a limit on the number of resources returned in the response data object.

Example:

  • https://your.statseeker.server/api/v2.1/cdt_cpu/ - will fall back to the default of 50 CPU objects in the response
  • https://your.statseeker.server/api/v2.1/cdt_cpu/?limit=5 - will return 5 CPU objects in the response
  • https://your.statseeker.server/api/v2.1/cdt_cpu/?limit=150 - will return 150 CPU objects in the response

The {field}_sort key can be used to sort the objects in the response data by the specified sort. For this to work, the field by which you are sorting must be included in the fields to return.

{field}_sort can be supplied as a comma separated list specifying the sort hierarchy and direction.

Sort Format
Configuration Data {field}_sort={rank}{direction}

E.g. name_sort=1,asc
Time-series Data {field}_sort={rank}{direction}{format}

E.g. RxUtil_sort=2,desc,avg 		Where:

  • rank: the sorting rank, 1 being the highest priority
  • direction: the sorting direction
  • format: the metric format being sorted on

Example:

  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=id,ipaddress&name_sort=1,desc

    The request will fail because we are attempting to sort on a field that has not been requested (name is not included as a value for the fields parameter), and therefore isn't contained within the response data

  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=id,ipaddress,name&name_sort=1,asc&limit=5

    Collect id, ipaddress and name details (fields=id,ipaddress,name)on all devices known to Statseeker, sort the devices alphabetically by name (name_sort=1,asc), and return details on the first five (limit=5)

This style of filtering becomes more useful when working with time-series data, for example.

  • https://your.statseeker.server/api/v2.1/cdt_cpu/?fields=deviceid,name,cpuLoad&cpuLoad_formats=avg&cpuLoad_sort=1,desc,avg&cpuLoad_timefilter=range%3Dnow%20-%2015m%20TO%20now%20-1m&limit=5

    Return details (fields=deviceid,name,cpuLoad) on the 5 CPU objects (limit=5) with the highest average load (cpuLoad_sort=1,desc,avg) over the last 15 minutes

  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=id,ipaddress,name,ping_rtt&ping_rtt_sort=1,desc,avg&limit=15&ping_rtt_formats=avg,vals&ping_rtt_timefilter=range%3Dnow%20-%205m%20TO%20now%20-1

    Return identification data as well as ping return trip (rtt) values for each ping request and the average rtt for each of 15 devices with the highest recorded average ping rtt over the last 15 minutes. Sort the results from highest to lowest average ping rtt

[top]

Filtering Using the Groups Key

All GET requests can include a groups key which can be used to filter the objects to be queried by the contents of specified Statseeker groups. Multiple groups can be specified as a list of comma separated values (e.g. groups=42505,42579, and whether multiple groups are handled in an AND or OR manner can be specified via the grouping_mode parameter.

Example:

  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=id,ipaddress,name&name_sort=1,asc&limit=5&groups=42505,42579&grouping_mode=AND

    Collect id, ipaddress and name details on all devices in the groups with an ID of 42505 or 42579. Filter those devices to only those which appear in both groups (grouping_mode=AND), sort the devices by name, and return details on the first five.

[top]


Field Filters

Field filters are applied at a field level to restrict the pool of resources that will be reported on and/or data returned. These filters use the format {field}_filter and accept either of an SQL-like query or an Extended Regular Expression (ERE). When providing an SQL-like query, the filter accepts both SQL operators (IS, LIKE, IN, BETWEEN, etc.) and wildcard characters (_ and %).

The field being filtered by must be included as a value of the fields parameter.

When your query is aggregating data, field filters can be applied both before and after data aggregation.

  • {field}_filter - use in the absence of data aggregation, or apply prior to aggregation occurring
  • {field}_post_filter - apply the filter after data aggregation has occurred
Note: in addition, when setting a {field}_filter for a time-series metric, you need to set a {field}_filter_format parameter.

E.g. RxUtil_filter_formats=avg.

This filter format must be one of the formats specified in either the global formats={formats} or metric-specific {field}_formats={formats} parameters. For details on field formats, see Timeseries Data: Stats and Formats.

Examples: SQL-like Filters

Use the syntax:

  • {field}_filter={operator}{value}
  • {field}_filter={operator}("{filter_string}")
  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=id,ping_rtt&name_filter=LIKE("%25rtr")&ping_rtt_formats=vals&ping_rtt_sort=1,desc,avg&ping_rtt_timefilter=range%3Dnow%20-%205m%20TO%20now%20-1

    This request will fail because it attempts to filter on the name field, but name was not included in the list of fields to retrieve (fields=id,ping_rtt.)

  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=id,name,ping_rtt&name_filter=LIKE("%25rtr")&ping_rtt_formats=vals&ping_rtt_sort=1,desc,avg&ping_rtt_timefilter=range%3Dnow%20-%205m%20TO%20now%20-1

    Return identification data as well as ping return trip (ping_rtt) values for each ping request and the average trip time for all requests in the last 5 minutes. Filter the response data to only those devices with the string rtr in their name; this naming convention has been applied to all routers on the target network. Sort those results by average ping time from highest to lowest.

Note: depending on the HTTP request library being used, there may be a requirement to manually URL encode various characters contained within URL strings. In the example above we URL encoded LIKE=("%rtr") because the % sign has a special meaning in a URL. Nested quotation marks and ampersands are other examples where URL encoding will usually be required in order for the browser to interpret the supplied URL correctly.
  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=name,ping_rttl&ping_rtt_formats=avg&ping_rtt_filter=>75&ping_rtt_filter_format=avg&ping_rtt_timefilter=range%3Dstart_of_today%20to%20now

    Return identification data as well as ping return trip (ping_rtt) values for each ping request, and the average trip time for all requests in the last 5 minutes. Filter the response data to only those devices with ping values greater than 75ms.

  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=name,ipaddress&ipaddress_filter=LIKE("10.100.44.%25")

    Return identification data for each device in the 10.100.44.0/24 subnet.

  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=id,name,ipaddress&ipaddress_filter=BETWEEN("10.100.44.0")%20AND%20("10.100.44.999")

    Return identification data for each device in the 10.100.44.0/24 subnet. The SQL BETWEEN operator will see an IP addresses as a string, so a final octet of .3 would be excluded from a range ending in .255. In our example we supplied a final octet of .999 to overcome this, and select all IP's in the 10.100.44.0/24 subnet.

  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=id,name,ipaddress&ipaddress_filter=IN("10.100.44.11","10.100.44.12","10.100.44.13")

    Return identification data for each device listed in the filter.

[top]

Examples: ERE Filters

Use the syntax:

  • {field}_filter=REGEXP'{filter_string}'
  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=id,name&name_filter=REGEXP%27rtr%27

    Return identification data for all devices with the string rtr in their name; this naming convention has been applied to all routers on the target network.

  • https://your.statseeker.server/api/v2.1/cdt_device/?fields=name,ipaddress&ipaddress_filter=REGEXP'^10\.100\.44\.([0-9]|[1-9][0-9]|1([0-9][0-9])|2([0-4][0-9]|5[0-5]))$'

    Return identification data for each device in the 10.100.44.0/24 subnet.

[top]


The Advanced Fields

The Advanced fields option (fields_adv) is another resource level filter (applied to fields belonging to a specified resource/object), and is a way to specify fields and associated filters in a single parameter. When fields_adv is specified, the API will ignore any fields parameter key:value pair included in the same request, as well as any of the following associated fields:

Parameters Type/Valid Values Description
{field}_formats Comma separated list, see Timeseries Data: Stats and Formats The formats to request from the API for the given field, required for timeseries data fields

Note: a global formats key (formats=) may also be used to apply the same values to all time-series metrics specified in fields
{field}_filter string The filter to apply to the given field
{field}_filter_format string The format to use for the filter, required for timeseries data fields
{field}_timefilter string The timefilter to use for the given field, required for timeseries data fields

Note: a global timefilter key (timefilter=) may also be used to apply the same values to all time-series metrics specified in fields
{field}_tz string An alternate timezone to use for the {field}_timefilter.

All timefilters use the Statseeker server's timezone unless an override is specified by supplying {field}_tz.

Note: a global timezone key (tz=) may also be used to apply the same values to all time-series metrics specified in fields
{field}_sort Comma separated list Comma separated list specifying the sort hierarchy and direction, in the following format: {field}_sort={rank}{direction} and for Time-series data: {field}_sort={rank}{direction}{format}
E.g. name_sort=1,asc
RxUtil_sort=1,desc,avg
{field}_states Comma separated list The states to use for the given field

The fields_adv can be used in place of the standard fields parameter, and can include all of the above fields as needed.

Example:

Return identification data, as well as ping return trip (ping_rtt) values and average value for the last 15mins, for each device known to Statseeker and sort these devices by the average ping, from highest to lowest

https://your.statseeker.server/api/v2.1/cdt_device/?fields_adv={"name":{"field":"name"},"id":{"field":"id"},"ipaddress":{"field":"ipaddress"},"ping":{"field":"ping_rtt","sort":{"priority":1,"order":"desc","format":"avg"},"formats":["avg","vals"],"timefilter":{"query":"range%3Dnow%20-%2015m%20TO%20now%20-1m"}}}


Note: the query has been URL encoded, non-essential spaces removed and required spaces replaced with '%20', etc.

When using the fields_adv parameter, the entire parameter is supplied in a JSON format and care should be taken when constructing this to ensure that:

  • sort priority is provided as an integer (not bounded by quotes), and not as a string
  • Values for the formats key are provided as an array (bounded in square brackets, [])
  • The timefilter is provided as a couple of nested key:value pairs, i.e.key:{key:value}

[top]


Time Filters

Time filters are required when requesting any timeseries data from Statseeker, so must be included in any request where either of the fields or fields_adv parameters include a timeseries metric.

Note: the API documentation Resource Reference details all available fields, for all available resources/objects, and timeseries data fields are clearly identified as such.

Timefilters should be specified in the following format:

Timefilter Format
Fields Timefilter {field}_timefilter=range=timefilter_query_string

E.g. ping_rtt_timefilter=range=now - 5m to now -1
Advanced Fields Timefilter "timefilter":{"query":"range=timefilter_query_string"}

E.g. fields_adv={"ping":{"field":"ping_rtt","formats":["avg","vals"],"timefilter":{"query":"range-now - 15m to now -1m"}}}

The timefilter query string should be specified in the same format as that displayed in the Query Info field in the Console, or time filter in the Report editor. When forming complex time filters it may be useful to make use of the Advanced Time Filter Editor, and its Test functionality, to preview the scope of the resulting time period prior to passing the time filter in an API request. For more details on time filters, the Advanced Time Editor and testing time filters, see Time Filters.

[top]


Global Time Filters

Rather than specifying individual {field}_timefilter parameters for every timeseries metric being requested, you can provide a global parameter that is applied to all.

timefilter={timefilter_query_string}

Examples:

  • URL Encoded: timefilter=range%3Dnow%20-15m%20TO%20now%20-1m
  • Raw: timefilter=range=now -15m to now -1m

Any instance of {field}_timefilter will override the global setting for that specific field only.

[top]