Maintenance Windows

The RPC API enables you to query future maintenance windows for a specific validator in the current epoch. These maintenance windows are block height ranges where the validator does not need to produce blocks or chunks.

Quick Reference

Method	Purpose	Parameters
`EXPERIMENTAL_maintenance_windows`	Get validator maintenance windows	`account_id`

Maintenance windows

Description

The maintenance windows for a specific validator are future block height ranges in current epoch, in which the validator does not need produce block or chunk. If the provided account is not a validator, then it will return the range from now to the end of the epoch.

method: EXPERIMENTAL_maintenance_windows
params:
- account_id: The validator account ID to query

Example

JSON
HTTPie
Lantstool

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "EXPERIMENTAL_maintenance_windows",
  "params": {
    "account_id": "node0"
  }
}

http POST https://rpc.testnet.near.org \
  jsonrpc=2.0 \
  id=dontcare \
  method=EXPERIMENTAL_maintenance_windows \
  params:='{
    "account_id": "node0"
  }'

Try it out on Lantstool

Loading...

Example response:

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "result": [
    [1028, 1031],
    [1034, 1038]
  ]
}

The result will be a list of future maintenance windows in current epoch. For example a window [1028, 1031] includes block heights 1028, 1029 and 1030.

Error handling:

When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the RPC Errors documentation.

Error Handling

Common Error Types

Error Code	Description	Solution
`UnknownAccount`	Account does not exist	Verify the account ID is correct and exists
`InvalidAccount`	Invalid account format	Use valid account ID format (e.g., `account.near`)
`InternalError`	Server internal error	Retry the request or try a different RPC endpoint
`RequestTimedOut`	Request timed out	Reduce request complexity or retry with timeout

Response Format

Successful responses return an array of maintenance window ranges:

Each window is represented as [start_height, end_height]
Ranges are inclusive of start height, exclusive of end height
Empty array indicates no maintenance windows for the validator

Best Practices

Cache results: Maintenance windows don't change frequently during an epoch
Monitor epoch changes: Query again when a new epoch starts

Quick Reference​