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
• Aggregations
• Interval
• Group By
• Order
• Timeframe (required)
• Limit

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:

Property	Description
property	Specifies the name of the property to filter.
operator	Specifies the filter operator to use.
value	The 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:

Operator	Description
eq	Equal to
ne	Not equal to
lt	Less than
lte	Less than or equal to
gt	Greater than
gte	Greater than or equal to
in	Whether 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]
contains	Whether or not the string property value contains the given sequence of characters.
contains_insensitive	Same as contains but case insensitive.
not_contains	Whether or not the string property value does not contain the given sequence of characters.
not_contains_insensitive	Same as not_contains but case insensitive.
regexp	Matching 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:

Property	Description
type	Specifies the name of the aggregation.
property	Specifies the property to run the operation on.

Example

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

Available aggregations are:

Operation	Description
count	Count the number of events.
count_unique	Count the number of events with unique values for a target property.
sum	Calculate the sum of all values for a target property.
min	Calculate the minimum value for a target property.
max	Calculate the maximum value for a target property.
median	Calculate the median value for a target property.
quantiles	Calculate the quantiles values for a target property.
avg	Calculate 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

Parameter	Description
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

Parameter	Description
from	A starting time value with the following format YYYY-MM-DDTHH:mm:ss.sssZ or YYYY-MM-DDTHH:mm:ssZ
to	An 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
}