Skip to main content
Last updated on

Cluster events API pagination changes

To improve API performance, Databricks is updating how pagination works in the Cluster events API.

On July 30, 2026, Databricks will deprecate the limit, offset, total_count, and next_page fields in the /api/2.1/clusters/events API endpoint. These fields will be replaced with new token-based pagination fields to improve API performance.

What's changing​

The cluster events API currently uses limit and offset-based pagination to retrieve batches of cluster events. This will be replaced with token-based pagination using the following new fields:

  • page_size (replaces limit)
  • page_token (replaces offset)
  • next_page_token (replaces next_page)
  • prev_page_token (new field for backward pagination)

The total_count field will also be removed from API responses.

Action required​

Before July 30, 2026, you must:

  1. Update any code that uses the cluster events API to use the new pagination fields instead of the deprecated fields.

  2. Update any third-party tooling or integrations that depend on the cluster events API to use the new pagination method.

API request examples​

The following examples show the deprecated pagination method and demonstrate how to use the new pagination method.

Deprecated pagination method​

The following example shows the deprecated pagination method that uses limit and offset:

JSON
curl -X POST \
  https://<databricks-instance-url>/api/2.1/clusters/events \
  -H 'Authorization: Bearer <databricks-auth-token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "cluster_id": "1234-567890-brick1",
        "start_time": 1617238800000,
        "end_time": 1619485200000,
        "event_types": ["STARTING", "TERMINATING"],
        "limit": 100,
        "offset": 0
      }'

The API response contained a next_page object that you would use to construct the next request.

New pagination method​

You can make the equivalent request using the new token-based pagination method using page_size:

JSON
curl -X POST \
  https://<databricks-instance-url>/api/2.1/clusters/events \
  -H 'Authorization: Bearer <databricks-auth-token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "cluster_id": "1234-567890-brick1",
        "start_time": 1617238800000,
        "end_time": 1619485200000,
        "event_types": ["STARTING", "TERMINATING"],
        "page_size": 100
      }'

The response will contain a next_page_token that you can use to retrieve the next page of events. You'll add this token to the page_token query parameter in the next request:

JSON
curl -X POST \
  https://<databricks-instance-url>/api/2.1/clusters/events \
  -H 'Authorization: Bearer <databricks-auth-token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "cluster_id": "1234-567890-brick1",
        "start_time": 1617238800000,
        "end_time": 1619485200000,
        "event_types": ["DRIVER_HEALTH_EVENT", "NODE_HEALTH_EVENT"],
        "page_size": 100,
        "page_token": "<next_page_token>"
      }'
On this page