Skip to main content

Querying Data

To query or analyze data, send a POST request to the <base_URI>/monitors/<monitor_id>/queries/<collection_id> endpoint, and add what you need from the following query parameters to the body:

note

To query data, you must be a logged in user, or fill the Authorization header with your API secret, in that case, the ID of the creator of the monitor will be used. This restriction is to prevent unauthorized users from querying the data of other users. It also prevents the developer from querying the data of the users.

Query Parameters

Filters

Filters enable you to refine the scope of events to be included in an query. Filters are sent as an array of JSON objects. Each JSON object (except Or Filters) has three properties, all of which are required:

PropertyDescription
propertySpecifies the name of the property to filter.
operatorSpecifies the filter operator to use.
valueThe value to compare to the property specified by property.

Example

{
"filters": [
{
"property": "price",
"operator": "gte",
"value": 1000
},
{
"property": "on_sale",
"operator": "eq",
"value": true
}
]
}

Avaliable operators are:

OperatorDescription
eqEqual to
neNot equal to
ltLess than
lteLess than or equal to
gtGreater than
gteGreater than or equal to
inWhether or not the property value is in a given set of values. The value passed in must be a JSON array of values. Example: [1,2,3,4,5]
containsWhether or not the string property value contains the given sequence of characters.
contains_insensitiveSame as contains but case insensitive.
not_containsWhether or not the string property value does not contain the given sequence of characters.
not_contains_insensitiveSame as not_contains but case insensitive.
regexpMatching property name with regular expression in property value.

Or Filters

For normal filters, all filters must match. For Or Filters, any of the filters must match.

{
"filters": [
{
"operator": "or",
"operands": [
{
"property": "price",
"operator": "gte",
"value": 0.99
},
{
"property": "on_sale",
"operator": "eq",
"value": true
}
]
}
]
}

Aggregations

Aggregations enable you to run an operation over the events. Aggregations are sent as an array of JSON objects. Each JSON object has two properties, all of which are required:

PropertyDescription
typeSpecifies the name of the aggregation.
propertySpecifies the property to run the operation on.

Example

{
"aggregations": [
{
"type": "sum",
"property": "cart_items_count"
}
]
}

Available aggregations are:

OperationDescription
countCount the number of events.
count_uniqueCount the number of events with unique values for a target property.
sumCalculate the sum of all values for a target property.
minCalculate the minimum value for a target property.
maxCalculate the maximum value for a target property.
medianCalculate the median value for a target property.
quantilesCalculate the quantiles values for a target property.
avgCalculate the average value for a target property.

Interval

The interval parameter helps you to build a histogram, it groups results into sub-timeframes.

This query parameter can help you answer questions such as:

How many purchases have been placed monthly, over the past year?

Example

{
"interval": "month"
}

Avaliable intervals

year, quarter, month, week, day, hour

note

Intervals doesn't work with group_by, if both are specified, the interval will be ignored.

Group by

The group_by parameter groups results categorically, by co-occurrence of a specified property.

This query parameter can help you answer questions such as:

  • How many orders were placed for each product?
  • How many users are coming from different countries?

Adding the group_by parameter changes the structure of the response to an array of objects containing:

  1. The unique value for the specified group_by property
  2. The result of the analysis

Example

{
"group_by": ["product_name", "country"]
}

Order

The order parameter orders the results returned by the query.

Example

{
"order": {
"by": "price",
"direction": "desc",
"type": "numeric"
}
}

Parameters

ParameterDescription
by (required)Property name. (Note: order.by has to be a property that is used in group_by or aggregations like price_sum, or _events_count)
direction (optional)Sorting direction. asc (default) or desc
type (optional)Sorting method. lexicographic (default), numeric

Timeframe

The timeframe parameter specifies a period of time over which to run an operations. This refines the scope of events that are included in the operation, based on when each event occurred.

Example

{
"timeframe": {
"from": "2022-02-25T19:00:00.000Z",
"to": "2023-02-25T19:00:00.000Z"
}
}

Required parameters

ParameterDescription
fromA starting time value with the following format YYYY-MM-DDTHH:mm:ss.sssZ or YYYY-MM-DDTHH:mm:ssZ
toAn end time value with the following format YYYY-MM-DDTHH:mm:ss.sssZ or YYYY-MM-DDTHH:mm:ssZ

Limit

The limit parameter limits the number of results returned.

Example

{
"limit": 10
}