Pagination unclear for search aggregate

Hi all, :slight_smile:

Can you please enhance the documentation for this API: search-aggregate | SailPoint Developer Community

I am aware of how regular pagination works for general list APIs, and also how the regular search API uses pagination, but this search-aggregate API is a special one. It returns both keys aggregations and hits. And the documentation does not mention how it applies pagination here. For both fields, or only one?

By simply testing this, it seems that the basic pagination iterates over the hits, but that the aggregations values are always the same. Is this a bug or is it meant to behave this way? In the later case, what would happen if the aggregations attribute yield too many results, will the API break into an error then? Would we need to apply a different way of paginating over the aggregations? Should the aggregations result show only data corresponding to the hits of the corresponding page?
How can we b sure that we can get all the results that should appear in the aggregation field if there are many results?

Kind regards,
Angelo