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 nameDescriptionAllowed operatorAllowed valueNotes
uidUnique user IDis, is_not, contains, not_contains<string>, [<string>, <string>, ...]value can be an array
user_emailUser email addressis, is_not, contains, not_contains<string>, [<string>, <string>, ...]value can be an array
user_nameUser nameis, is_not, contains, not_contains<string>, [<string>, <string>, ...]value can be an array
location_ipUser location IP addressis, is_not, contains, not_contains<string>, [<string>, <string>, ...]value can be an array
landing_urlURL where user came to your projectis, is_not, contains, not_contains<string>, [<string>, <string>, ...]value can be an array
exit_urlURL where user exitedis, is_not, contains, not_contains<string>, [<string>, <string>, ...]value can be an array
source_refererURL of the referrer website the user visited before coming your your projectis, is_not, contains, not_contains<string>, [<string>, <string>, ...]value can be an array
recording_urlURL your user visited on your website projectis, is_not, contains, not_contains<string>, [<string>, <string>, ...]value can be an array
session_durationDuration of the sessionlte, gte<number>lte—less than or equal
gte—greater than or equal
recording_dateDate of the session recordingbefore, 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_screenMobile application screen nameis, 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"
    }
}