Searching sessions

You can use the REST API to search in your user sessions by adding filters to your POST call. For more information, see Search sessions in the API documentation.

Filtering user sessions

To search your user sessions using the REST API, you need to provide a filters array. If you want the response sorted in a particular way, you can add an optional sort object.

Filters format

Objects in the filters array must contain three parameters: name, operator, and value.

// required filter object format
{
	"name": "<name of the object>",
	"operator": "is"|"is_not"|"contains"|"not_contains",
	"value": <string>|[<string>,<string>...]
}

The following table contains all possible combinations of operators and values for each possible filter.

Filter name	Description	Allowed operator	Allowed value	Notes
`uid`	Unique user ID	`is`, `is_not`, `contains`, `not_contains`	`<string>`, `[<string>, <string>, ...]`	`value` can be an array
`user_email`	User email address	`is`, `is_not`, `contains`, `not_contains`	`<string>`, `[<string>, <string>, ...]`	`value` can be an array
`user_name`	User name	`is`, `is_not`, `contains`, `not_contains`	`<string>`, `[<string>, <string>, ...]`	`value` can be an array
`location_ip`	User location IP address	`is`, `is_not`, `contains`, `not_contains`	`<string>`, `[<string>, <string>, ...]`	`value` can be an array
`landing_url`	URL where user came to your project	`is`, `is_not`, `contains`, `not_contains`	`<string>`, `[<string>, <string>, ...]`	`value` can be an array
`exit_url`	URL where user exited	`is`, `is_not`, `contains`, `not_contains`	`<string>`, `[<string>, <string>, ...]`	`value` can be an array
`source_referer`	URL of the referrer website the user visited before coming your your project	`is`, `is_not`, `contains`, `not_contains`	`<string>`, `[<string>, <string>, ...]`	`value` can be an array
`recording_url`	URL your user visited on your website project	`is`, `is_not`, `contains`, `not_contains`	`<string>`, `[<string>, <string>, ...]`	`value` can be an array
`session_duration`	Duration of the session	`lte`, `gte`	`<number>`	`lte`—less than or equal `gte`—greater than or equal
`recording_date`	Date of the session recording	`before`, `after`, `is` `in_range`	`<string>`, `[<string>, <string>, ...]` `[<string>, <string>]`	Must be a date. When using `in_range`, must be an array with `["from date", "to date"]`
`mobile_event_screen`	Mobile application screen name	`is`, `is_not`, `contains`, `not_contains`	`<string>`, `[<string>, <string>, ...]`	`value` can be an array For more information, see Recording navigation and heatmaps

Logical OR condition

You can enter an array as value to include an OR statement.

{
	"name": "<name of the object>",
	"operator": "is"|"is_not"|"contains"|"not_contains",
	"value": [<string>,<string>...]
}

Response sorting

You can also add the optional sort object. If you do not add sort, the default sort is asc.

{timeStart: 'asc'|'desc'}

Query limit

You can add a limit parameter to your query. The default limit is 10 and the maximum is 100.

POST https://api.eu.smartlook.cloud/api/v1/sessions/search?limit=10

Example user session searches

Example 1: Search for sessions that are 30-40 seconds in length

You want to find all sessions that are 30-40 seconds. To find user sessions that match your needs, you need to add two filters to your POST:

POST https://api.eu.smartlook.cloud/api/v1/sessions/search
{
    "filters": [
        {
            "name": "session_duration",
            "operator": "lte",
            "value": 40
        },
        {
            "name": "session_duration",
            "operator": "gte",
            "value": 30
        }
    ],
    "sort": {
        "timeStart": "asc"
    }
}

The filters used in the example contain the name of the filter session_duration, the operators lte (less than or equal to) and gte (greater than or equal to), and the values of 30 and 40. The final parameter, sort, allows you to tell how you would like your results sorted.

The response returns all user sessions that are 30-40 seconds.

Example 2: Search for sessions from two users

You want to find sessions for two users by uid to be sorted by timestart in asc order. To find user sessions that match your needs, you need to use one filter with two IDs in value array.

POST https://api.eu.smartlook.cloud/api/v1/sessions/search
{
    "filters": [
        {
            "name": "uid",
            "operator": "is",
            "value": ["some-user-id-1", "some-user-id-2"]
        }
    ],
    "sort": {
        "timeStart": "asc"
    }
}