In previous articles like: [BioStar 2 API] How To Retrieve Events Logs it is being addressed how to retrieve events on demand using the BioStar 2 API.


In this article a simple example is given to understand how to Implement pagination when searching for Events.


Why is this important:

There are a considerable amount of events that cannot be retrieved in only one API call.

  • Trying to retrieve more than 10,000 events could be cumbersome and could introduce unnecessary server load and burst in network and server processing power.
  • It could be also rejected as the API response could reach a timeout by either the BioStar 2 DB could be still processing a very large dataset while the network timeout was reached,
  • or the REST API call max size stack was also reached.


Warning:

If your integration retrieves a large volume of historical events without pagination, the API request may cause excessive server load, timeout, or exceed the REST API response size limit. This can cause your integration become unstable and may eventually lead to a server crash, delayed, incomplete, or duplicated event records depending on how the external system handles failed requests.


To avoid the latter, making also your implementation easier to scale and enhance your implementation in general terms by making it efficient, try the following:


Example:

{
  "Query": {
    "limit": 500,
     "hint" : "...", 
    "conditions": [
      {
        "column": "datetime",
        "operator": 3,
        "values": [
          "2025-11-04T00:00:00.000Z","2025-11-04T23:59:59.000Z"
        ]
      }
    ],
    "orders": [
      {
        "column": "datetime",
        "descending": false
      }
    ]
  }
} 

Here's a detailed explanation of how hint works. 
It's not going to work if you put only the hint. You still need to put in the mandatory parameters - "limit".

For example, in the below screenshot, it is initially called: POST api/events/search with limit of 3 records.


Then get the following response with 3 records - id (using 3 only for the sake of the explanation) : 32, 31, 24.

"EventCollection": {

    "rows": [

        {

            "id": "32",

            "server_datetime": "2024-07-10T04:40:38.00Z",

            "datetime": "2024-07-09T19:40:38.00Z",

            "index": "2461",

            "user_group_id": {

                "id": "0",

                "name": ""

            },

            "device_id": {

                "id": "543458315",

                "name": "X-Station 2 543458315 (192.168.40.47)"

            },

            "event_type_id": {

                "code": "12800"

            },

            "is_dst": "0",

            "timezone": {

                "half": "1",

                "hour": "4",

                "negative": "0"

            },

            "user_update_by_device": "false",

            "hint": "172055403805434583150000002461",

            "user_id": {

                "photo_exists": "false"

            }

        },

        {

            "id": "31",

            "server_datetime": "2024-07-10T04:40:38.00Z",

            "datetime": "2024-07-09T19:40:32.00Z",

            "index": "2460",

            "user_group_id": {

                "id": "0",

                "name": ""

            },

            "device_id": {

                "id": "543458315",

                "name": "X-Station 2 543458315 (192.168.40.47)"

            },

            "event_type_id": {

                "code": "12800"

            },

            "is_dst": "0",

            "timezone": {

                "half": "1",

                "hour": "4",

                "negative": "0"

            },

            "user_update_by_device": "false",

            "hint": "172055403205434583150000002460",

            "user_id": {

                "photo_exists": "false"

            }

        },

        {

            "id": "24",

            "server_datetime": "2024-07-08T08:56:19.00Z",

            "datetime": "2024-07-07T23:56:16.00Z",

            "index": "2459",

            "user_group_id": {

                "id": "0",

                "name": ""

            },

            "device_id": {

                "id": "543458315",

                "name": "X-Station 2 543458315 (192.168.40.47)"

            },

            "event_type_id": {

                "code": "15104"

            },

            "is_dst": "0",

            "timezone": {

                "half": "1",

                "hour": "4",

                "negative": "0"

            },

            "user_update_by_device": "false",

            "hint": "172039657605434583150000002459",

            "user_id": {

                "photo_exists": "false"

            }

        }

    ]

}


Next, let's say I'm going to call the POST /api/events/search with "hint" value set to 172055403805434583150000002461 which is the hint value of log with id "32"
And make sure to include the "limit" field. 


Then, in the response, I'm getting the following three logs with id : 31, 24, 23
As you can see, because the hint value was for log id "32" as you have seen above, now it's showing me the next three logs starting with log id "31".

"EventCollection": {

    "rows": [

        {

            "id": "31",

            "server_datetime": "2024-07-10T04:40:38.00Z",

            "datetime": "2024-07-09T19:40:32.00Z",

            "index": "2460",

            "user_group_id": {

                "id": "0",

                "name": ""

            },

            "device_id": {

                "id": "543458315",

                "name": "X-Station 2 543458315 (192.168.40.47)"

            },

            "event_type_id": {

                "code": "12800"

            },

            "is_dst": "0",

            "timezone": {

                "half": "1",

                "hour": "4",

                "negative": "0"

            },

            "user_update_by_device": "false",

            "hint": "172055403205434583150000002460",

            "user_id": {

                "photo_exists": "false"

            }

        },

        {

            "id": "24",

            "server_datetime": "2024-07-08T08:56:19.00Z",

            "datetime": "2024-07-07T23:56:16.00Z",

            "index": "2459",

            "user_group_id": {

                "id": "0",

                "name": ""

            },

            "device_id": {

                "id": "543458315",

                "name": "X-Station 2 543458315 (192.168.40.47)"

            },

            "event_type_id": {

                "code": "15104"

            },

            "is_dst": "0",

            "timezone": {

                "half": "1",

                "hour": "4",

                "negative": "0"

            },

            "user_update_by_device": "false",

            "hint": "172039657605434583150000002459",

            "user_id": {

                "photo_exists": "false"

            }

        },

        {

            "id": "23",

            "server_datetime": "2024-07-08T08:56:19.00Z",

            "datetime": "2024-07-07T23:48:18.00Z",

            "index": "2458",

            "user_group_id": {

                "id": "0",

                "name": ""

            },

            "device_id": {

                "id": "543458315",

                "name": "X-Station 2 543458315 (192.168.40.47)"

            },

            "event_type_id": {

                "code": "15360"

            },

            "is_dst": "0",

            "timezone": {

                "half": "1",

                "hour": "4",

                "negative": "0"

            },

            "user_update_by_device": "false",

            "hint": "172039609805434583150000002458",

            "user_id": {

                "photo_exists": "false"

            }

        }

    ]

}


And so on, 


IMPORTANT NOTES: