API search functions

Our API documentation is available here:

But the three key sections relating to Search are:

Once you know the orgName you wish to search on and the relevant table you can start searching. For all the examples below, we will be using `org-name` as the orgName and `data` as the table.  `data` is a default table, will appear as you install new agents and contains CPU usage.

Getting started

Simply calling on the Search endpoint with no parameters will return a sample of 50 rows sorted in chronological order (that is, ascending event_time)


`fields` is an array of strings.  Valid field names can be found by looking at the Table Metadata or simply examining the field names return by a default search. The standard way to encode arrays as query parameter is to include the target parameter multiple times, e.g. to select only the fields `device` and `event_time`, the query would be:


`sort` takes a single field name and will sort the returned records based on this field.  To sort in descending order, simply add a minus sign (hyphen) before the field name, e.g.


`rows` is an integer defining the maximum number of rows you wish to receive.  The maximum supported number of rows is 10,000.


`filters` is an "Array[Filter]". You can find the Filter definition in the Request section of the API documentation, just below the Parameters table. A Filter is a JSON object consisting of a field, an operator and a value. You can get a list of operators, and what they expect in the value field, from the documentation. As an Array, this parameter is treated in the same way as `fields`, simply list the `filters` parameter multiple times. The difference is that each Filter is an object, so you will need to serialize and encode the object for use as part of a URL. For example, let's say I have the following filter (keeping in mind that all filters are AND based to keep the API as simple as possible. Date fields will accept any ISO 8601 compliant date and time string):

    "field": "event_time",
    "operator": ">=",
    "value": "2017-03-10T00:00:00Z"
    "field": "cpu_usage",
    "operator": ">",
    "value": 50

This translates to the following URL:

Generally speaking (depending on the framework or application you are using) you shouldn't have to worry about these specific implementation details like URL encoding and listing query parameters multiple times. Instead you should be able to simply build an Array of Objects and the framework will handle the rest (including parsing the JSON response).


`timeframe` is a string field with the primary goal of making it easier for a human to select a window of time dynamically. For example, the timeframe "2 days ago" will translate to "event_time >= 2017-03-08T00:00:00" if I run it on the 10th of March, but it will generate a different filter if I run it a week later (I have deliberately left off the timezone offset as this translation depends on the `timezone` field). While not generally used in API-only queries, you are more than welcome to use it if it helps. Here's the help article detailing other examples of timeframe usage. You can safely ignore the `timezone` field if you are not using this feature.

Complete Example 

To select the latest value for a given field (e.g. `cpu_usage`) and deviceId (e.g. `4a96a4a6-606c-438d-a236-ec76559cb415`) you would run the following search:

Here's a quick breakdown:

  • Sort by event_time in descending (reverse chronological) order
  • Select 1 row
  • Only show the event_time and cpu_usage fields
  • Only show values for deviceId `4a96a4a6-606c-438d-a236-ec76559cb415`: {"field":"source","operator":"=","value":"4a96a4a6-606c-438d-a236-ec76559cb415"}



Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Article is closed for comments.