Genesys Cloud
Upcoming release of new usage query service with expanded data access and pagination

Announced on Effective date Aha! idea
2025-04-21 - -

Genesys Cloud introduced a new usage-query-service, a replacement of the existing public-api-usage-query-service, to improve how customers access and interact with their usage data. On March 31, 2025, you can use this new service to run asynchronous queries across a broader set of data, not just public API usage. The new service supports full pagination and page size controls.

Why this change matters?

This change aims to give customers better access and visibility into their platform usage and to support future expansion into other datasets beyond public API usage. Previously, the public API usage endpoints applied strict filters; for example, excluding some system-level org IDs, and lacked pagination. 

With the new service, customers will:

  • Experience greater control over their queries, including advanced filters by client ID, platform, user ID, HTTP method, and more.
  • Access complete data that was previously hidden (for example, OAuth clients like purecloud or purecloud-builtin are now included).
  • Receive data faster and more reliably with asynchronous query jobs.
  • Paginate through results, avoiding limitations on large result sets and gaining the ability to manage output size.

Limitations

The data made available by this service includes all usage activity, not just billable data. Customers should not use this API to determine billing. The service does not define what is or is not billable.

New available endpoints

  • POST /api/v2/usage/aggregates/query/jobs
  • GET /api/v2/usage/aggregates/query/jobs/{jobId}
  • POST /api/v2/usage/client/{clientId}/aggregates/query/jobs
  • GET /api/v2/usage/client/{clientId}/aggregates/query/jobs/{jobId}

Endpoints for deprecation

  • Various api/v2/usage/query and api/v2/oauth/clients/{clientId}/usage endpoints

Transition details

Customers are encouraged to migrate to the new endpoints for a complete and customizable view of their usage data.