Pagination

The Events API uses cursor-based pagination, which is useful for working with large datasets. In response to each request, the API returns a unique ID (cursor) that indicates where you left off retrieving data. On the next call, you can provide that cursor to continue fetching events starting from the next point in the dataset so no records are missed.

There are two types of cursors used in calls to the API: a reset cursor and a cursor (also called a continuing cursor).

Reset cursor

A reset cursor is used for the first request you make to the API to create a new point from which to start fetching data. You can also use a reset cursor any time you need to reset the parameters of your cursor – such as the number of records to return with each request – or go back to an earlier point in the records.

For the first POST request you make to the API, you must include a ResetCursor object with an optional start time, end time, and limit parameters in the request body. The return will include a cursor in the response body that can be used in the next call made to the API. If no parameters are provided, the API will use the default values indicated in the schema.

For example:

Example reset cursor request

ResetCursor object schema

Name	Type	Description
limit (optional)	number	The number of events to return in a single request. Specify a limit from 1 to 1000. If not specified, limit will default to 100. To return additional events, use the cursor position for subsequent requests.
start_time (optional)	string	The date and time to start retrieving events. Uses the RFC 3339 standard. If not specified, start_time will default to one hour before specified end_time. If no end_time is specified, start_time will default to one hour ago.
end_time (optional)	string	The date and time to stop retrieving events. Uses the RFC 3339 standard.

Cursor

For continued calling of the API, include the cursor from the previous response in the request body of your next call to the API, instead of the ResetCursor object. This will start fetching data from the last indicated position to avoid missing any data.

Example cursor

Cursor object schema

Name	Type	Description
cursor	string	Cursor to fetch more data, if available, or continue the polling process. Use the cursor returned in the response body of your previous to the endpoint. For example: aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK.

The 1Password Events API apps for Splunk and Elastic will store the cursor position for future requests.