Analytics API paging object pageSize vs pageCount behavior

NICE CXone API & Integrations
1
  • I can’t seem to figure out why the paging object returned by the CXone Analytics API seems to ignore my pageSize request when the total record count is high. We’re pulling agent performance metrics via POST /api/v2/analytics/agents/schedules for a specific date range, and the response structure is inconsistent with what the documentation implies about pagination limits.
  • The request payload explicitly sets “pageSize”: 200 and “pageNumber”: 1, which should return exactly 200 records if available. Instead, the response contains only 50 records, yet “pageCount”: 4 is returned, suggesting there are more pages. This contradicts the expectation that pageSize controls the chunk size per request.
  • Here is the relevant snippet from our Studio sub-script using GetRESTProxy:
{
"method": "POST",
"url": "/api/v2/analytics/agents/schedules",
"body": {
"dateFrom": "2023-10-01T00:00:00Z",
"dateTo": "2023-10-01T23:59:59Z",
"pageSize": 200,
"pageNumber": 1,
"groupings": ["agentId"]
}
}
  • The response header includes “X-Paging-TotalCount”: 200, but the body only lists 50 agents. The paging object in the response shows “pageSize”: 50, overriding the request parameter. Is this a hardcoded limit for agent schedule queries specifically?
  • We’ve tried adjusting pageNumber to 2, which returns the next 50 records, confirming the server is enforcing a 50-record cap per page regardless of the input. This breaks our logic in the main flow where we loop through pageCount to aggregate data.
  • The documentation for the Analytics API doesn’t explicitly state a maximum pageSize for this endpoint, unlike other endpoints like /api/v2/users which clearly document a 250 record limit. Could this be a backend configuration issue or a known constraint?
  • Any insights on how to handle this discrepancy in Studio? We’re currently working around it by looping until the response array is empty, but that’s inefficient. Need to know if there’s a way to force larger chunks or if we must accept the 50-record limit.
2

If I remember correctly…

The request payload explicitly sets “pageSize”: 200 and “pageNumber”: 1, which should return exactly 200 records if

the backend ignores pageSize if it exceeds the hard limit for that specific endpoint. for analytics/agents/schedules, max is usually 1000, but sometimes it caps lower depending on the complexity of the query. don’t trust pageCount either. it’s often a rough estimate until the last page is fetched.

here’s how i handle it in my pact consumer tests to ensure the mock provider behaves correctly:

// pact setup
provider
 .given('agent schedules exist for date range')
 .uponReceiving('a request for page 1')
 .withRequest({
 method: 'POST',
 path: '/api/v2/analytics/agents/schedules',
 body: {
 dateFrom: '2023-10-01T00:00:00.000Z',
 dateTo: '2023-10-02T00:00:00.000Z',
 pageSize: 200,
 pageNumber: 1
 }
 })
 .willRespondWith({
 body: {
 pageSize: 200,
 pageNumber: 1,
 pageCount: 5, // mock value
 total: 1000,
 entities: Array(200).fill({}) // mock data
 }
 });

check the total field. if total > pageSize * pageNumber, keep fetching. the api docs are sometimes vague on this. i’ve seen it truncate silently.

3

The documentation actually says… analytics endpoints enforce a hard cap of 1000 items per page, regardless of your input.

i hit this in Go last week. the server silently truncates. here’s how i handle it:

req := platform.NewPostAnalyticsAgentsSchedulesRequest()
req.Body.SetPageSize(1000) // max allowed

check response.Paging.pageCount to loop. don’t guess.

4

right, 1000 is the hard cap. my vue composables just chunk requests at 950 to be safe. don’t fight the limit.

{
 "pageSize": 1000,
 "pageNumber": 1
}

it’ll truncate silently if you push higher. just loop through pageCount.