> ## Documentation Index
> Fetch the complete documentation index at: https://developers.avacloud.io/llms.txt
> Use this file to discover all available pages before exploring further.
# List validators
> Lists details for validators. By default, returns details for all validators. The nodeIds parameter supports substring matching. Filterable by validation status, delegation capacity, time remaining, fee percentage, uptime performance, and subnet id.
## OpenAPI
````yaml get /v1/networks/{network}/validators
openapi: 3.1.0
info:
title: Data API
description: >-
The Data API provides web3 application developers with multi-chain data
related to Avalanche's primary network, Avalanche subnets, and Ethereum.
With Data API, you can easily build products that leverage real-time and
historical transaction and transfer history, native and token balances, and
various types of token metadata. The API is in Beta and may be subject to
change.If you have feedback or feature requests for the API,
please submit them here.
Bug reports can be submitted here,
and any potential security issues can be reported here.
version: 1.0.0
contact: {}
servers:
- url: https://glacier-api.avax.network
security:
- apiKey: []
- {}
tags:
- name: EVM Chains
description: >-
Find information about indexed EVM-compatible chains, such as the
Avalanche C-Chain.
- name: EVM Blocks
description: >-
Find information about blocks on EVM-compatible chains, such as the
Avalanche C-Chain.
- name: EVM Transactions
description: >-
Find information about transactions on EVM-compatible chains, such as the
Avalanche C-Chain.
- name: EVM Balances
description: >-
Find information about balances on EVM-compatible chains, such as the
Avalanche C-Chain.
- name: EVM Contracts
description: >-
Find information about contracts on EVM-compatible chains, such as the
Avalanche C-Chain.
- name: Primary Network
- name: Primary Network Blocks
description: >-
Find information about blocks on Avalanche's Primary Network Chains - the
P-Chain, the X-Chain, and the C-Chain.
- name: Primary Network Vertices
description: Find information about vertices on Avalanche's X-Chain.
- name: Primary Network Transactions
description: >-
Find information about transactions on Avalanche's Primary Network Chains
- the P-Chain, the X-Chain, and the C-Chain.
- name: Primary Network Balances
description: >-
Find information about balances on Avalanche's Primary Network Chains -
the P-Chain, the X-Chain, and the C-Chain.
- name: Primary Network UTXOs
description: >-
Find information about utxos on Avalanche's Primary Network Chains - the
P-Chain, the X-Chain, and the C-Chain.
- name: Primary Network Rewards
description: Find information about rewards on Avalanche's Primary Network.
- name: NFTs
- name: Operations
- name: Health Check
- name: Teleporter
description: Find information about Teleporter transactions.
- name: Interchain Messaging
description: Find information about Interchain Messaging transactions.
- name: Webhooks
description: Manage webhooks and get notified for various onchain activities.
- name: RPC
description: Interact with chain nodes using JSON-RPC.
- name: Data API Usage Metrics
description: Usage metrics and logs for the Data API.
- name: Signature Aggregator
description: Request signatures for a Warp message from Subnet validators
- name: Notifications
description: Get notifications for validator status and activity issues.
- name: AVAX Supply
description: Find information about AVAX supply.
paths:
/v1/networks/{network}/validators:
get:
tags:
- Primary Network
summary: List validators
description: >-
Lists details for validators. By default, returns details for all
validators. The nodeIds parameter supports substring matching.
Filterable by validation status, delegation capacity, time remaining,
fee percentage, uptime performance, and subnet id.
operationId: listValidators
parameters:
- name: pageToken
required: false
in: query
description: >-
A page token, received from a previous list call. Provide this to
retrieve the subsequent page.
schema:
type: string
- name: pageSize
required: false
in: query
description: >-
The maximum number of items to return. The minimum page size is 1.
The maximum pageSize is 100.
schema:
type: integer
default: 10
minimum: 1
maximum: 100
example: '10'
- name: network
required: true
in: path
description: Either mainnet or testnet/fuji.
example: mainnet
schema:
$ref: '#/components/schemas/Network'
- name: nodeIds
required: false
in: query
description: >-
A comma separated list of node ids to filter by. Supports substring
matching.
example: NodeID-111111111111111111116DBWJs,NodeID-222222222222222222227DBWJs
schema:
type: string
- name: sortBy
required: false
in: query
description: >-
Which property to sort by, in conjunction with sortOrder.
Note: Delegation fee is only available for mainnet validators. Set
`subnetId` to `11111111111111111111111111111111LpoYY` to use this
option.
schema:
$ref: '#/components/schemas/SortByOption'
- name: sortOrder
required: false
in: query
example: asc
description: >-
The order by which to sort results. Use "asc" for ascending order,
"desc" for descending order. Sorted by timestamp or the `sortBy`
query parameter, if provided.
schema:
$ref: '#/components/schemas/SortOrder'
- name: validationStatus
required: false
in: query
description: Validation status of the node.
example: completed
schema:
$ref: '#/components/schemas/ValidationStatusType'
- name: minDelegationCapacity
required: false
in: query
description: >-
The minimum delegation capacity, in nAVAX, used to filter the set of
nodes being returned. Accepts values between 0 and
720,000,000,000,000,000
example: '0'
schema:
type: string
- name: maxDelegationCapacity
required: false
in: query
description: >-
The maximum delegation capacity, in nAVAX, used to filter the set of
nodes being returned. Accepts values between 0 and
720,000,000,000,000,000.
example: '720000000000000000'
schema:
type: string
- name: minTimeRemaining
required: false
in: query
description: >-
The minimum validation time remaining, in seconds, used to filter
the set of nodes being returned.
example: 0
schema:
type: number
maximum: 2147483647
minimum: 0
- name: maxTimeRemaining
required: false
in: query
description: >-
The maximum validation time remaining, in seconds, used to filter
the set of nodes being returned.
example: 2147483647
schema:
type: number
maximum: 2147483647
minimum: 0
- name: minFeePercentage
required: false
in: query
description: >-
The minimum fee percentage, used to filter the set of nodes being
returned. If this field is populated no subnet validations will be
returned, as their fee percentage is null, since subnet delegations
are not supported. Default is 2.0, as per the Avalanche spec.
example: 2
schema:
type: number
maximum: 100
minimum: 2
- name: maxFeePercentage
required: false
in: query
description: >-
The maximum fee percentage, used to filter the set of nodes being
returned. If this field is populated no subnet validations will be
returned, as their fee percentage is null, since subnet delegations
are not supported. Default is 100.0.
example: 100
schema:
type: number
maximum: 100
minimum: 2
- name: minUptimePerformance
required: false
in: query
description: >-
The minimum node uptime performance percentage, which represents
node health, used to filter the set of nodes being returned Default
is 90.
example: 90
schema:
type: number
maximum: 100
minimum: 0
- name: maxUptimePerformance
required: false
in: query
description: >-
The maximum node uptime performance percentage, which represents
node health, used to filter the set of nodes being returned. Default
is 100.
example: 100
schema:
type: number
maximum: 100
minimum: 0
- name: subnetId
required: false
in: query
description: >-
The subnet ID to filter by. If not provided, then all subnets will
be returned.
example: 11111111111111111111111111111111LpoYY
schema: {}
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListValidatorDetailsResponse'
'400':
description: |-
Bad requests generally mean the client has passed invalid
or malformed parameters. Error messages in the response could help in
evaluating the error.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
'401':
description: |-
When a client attempts to access resources that require
authorization credentials but the client lacks proper authentication
in the request, the server responds with 401.
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
'403':
description: |-
When a client attempts to access resources with valid
credentials but doesn't have the privilege to perform that action,
the server responds with 403.
content:
application/json:
schema:
$ref: '#/components/schemas/Forbidden'
'404':
description: |-
The error is mostly returned when the client requests
with either mistyped URL, or the passed resource is moved or deleted,
or the resource doesn't exist.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
'429':
description: |-
This error is returned when the client has sent too many,
and has hit the rate limit.
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequests'
'500':
description: |-
The error is a generic server side error that is
returned for any uncaught and unexpected issues on the server side.
This should be very rare, and you may reach out to us if the problem
persists for a longer duration.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'502':
description: |-
This is an internal error indicating invalid response
received by the client-facing proxy or gateway from the upstream server.
content:
application/json:
schema:
$ref: '#/components/schemas/BadGateway'
'503':
description: |-
The error is returned for certain routes on a particular
Subnet. This indicates an internal problem with our Subnet node, and may
not necessarily mean the Subnet is down or affected.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailable'
x-codeSamples:
- lang: javascript
label: JavaScript
source: |-
import { Avalanche } from "@avalanche-sdk/chainkit";
const avalanche = new Avalanche({
network: "mainnet",
});
async function run() {
const result = await avalanche.data.primaryNetwork.listValidators({
pageSize: 10,
nodeIds: "NodeID-111111111111111111116DBWJs,NodeID-222222222222222222227DBWJs",
sortOrder: "asc",
validationStatus: "completed",
minDelegationCapacity: "0",
maxDelegationCapacity: "720000000000000000",
minTimeRemaining: 0,
maxTimeRemaining: 2147483647,
minFeePercentage: 2,
maxFeePercentage: 100,
minUptimePerformance: 90,
maxUptimePerformance: 100,
subnetId: "11111111111111111111111111111111LpoYY",
});
for await (const page of result) {
console.log(page);
}
}
run();
components:
schemas:
Network:
type: string
enum:
- mainnet
- fuji
- testnet
SortByOption:
type: string
enum:
- blockIndex
- delegationCapacity
- timeRemaining
- delegationFee
- uptimePerformance
SortOrder:
type: string
enum:
- asc
- desc
ValidationStatusType:
type: string
enum:
- completed
- active
- pending
- removed
ListValidatorDetailsResponse:
type: object
properties:
nextPageToken:
type: string
description: >-
A token, which can be sent as `pageToken` to retrieve the next page.
If this field is omitted or empty, there are no subsequent pages.
validators:
type: array
items:
oneOf:
- $ref: '#/components/schemas/CompletedValidatorDetails'
- $ref: '#/components/schemas/ActiveValidatorDetails'
- $ref: '#/components/schemas/PendingValidatorDetails'
- $ref: '#/components/schemas/RemovedValidatorDetails'
discriminator:
propertyName: validationStatus
mapping:
active: '#/components/schemas/ActiveValidatorDetails'
pending: '#/components/schemas/PendingValidatorDetails'
completed: '#/components/schemas/CompletedValidatorDetails'
removed: '#/components/schemas/RemovedValidatorDetails'
description: The list of validator Details.
required:
- validators
BadRequest:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 400
error:
type: string
description: The type of error
examples:
- Bad Request
required:
- message
- statusCode
- error
Unauthorized:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 401
error:
type: string
description: The type of error
examples:
- Unauthorized
required:
- message
- statusCode
- error
Forbidden:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 403
error:
type: string
description: The type of error
examples:
- Forbidden
required:
- message
- statusCode
- error
NotFound:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 404
error:
type: string
description: The type of error
examples:
- Not Found
required:
- message
- statusCode
- error
TooManyRequests:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 429
error:
type: string
description: The type of error
examples:
- Too Many Requests
required:
- message
- statusCode
- error
InternalServerError:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 500
error:
type: string
description: The type of error
examples:
- Internal Server Error
required:
- message
- statusCode
- error
BadGateway:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 502
error:
type: string
description: The type of error
examples:
- Bad Gateway
required:
- message
- statusCode
- error
ServiceUnavailable:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 503
error:
type: string
description: The type of error
examples:
- Service Unavailable
required:
- message
- statusCode
- error
CompletedValidatorDetails:
type: object
properties:
txHash:
type: string
nodeId:
type: string
subnetId:
type: string
amountStaked:
type: string
delegationFee:
type: string
description: >-
The percentage of total estimated delegator rewards allocated to
validator nodes for supporting delegations.
startTimestamp:
type: number
endTimestamp:
type: number
blsCredentials:
description: Present for AddPermissionlessValidatorTx
allOf:
- $ref: '#/components/schemas/BlsCredentials'
delegatorCount:
type: number
amountDelegated:
type: string
rewards:
$ref: '#/components/schemas/Rewards'
validationStatus:
type: string
enum:
- completed
required:
- txHash
- nodeId
- subnetId
- amountStaked
- startTimestamp
- endTimestamp
- delegatorCount
- rewards
- validationStatus
ActiveValidatorDetails:
type: object
properties:
txHash:
type: string
nodeId:
type: string
subnetId:
type: string
amountStaked:
type: string
delegationFee:
type: string
description: >-
The percentage of total estimated delegator rewards allocated to
validator nodes for supporting delegations.
startTimestamp:
type: number
endTimestamp:
type: number
blsCredentials:
description: Present for AddPermissionlessValidatorTx
allOf:
- $ref: '#/components/schemas/BlsCredentials'
stakePercentage:
type: number
description: >-
The percentage of this validator's stake amount to the total active
stake.
delegatorCount:
type: number
description: The number of delegators linked to the validator.
amountDelegated:
type: string
description: The total amount in nAVAX delegated to the validator.
uptimePerformance:
type: number
description: >-
The validator's uptime percentage, as observed by our internal node
and measured over time.
avalancheGoVersion:
type: string
delegationCapacity:
type: string
description: >-
The amount of stake in nAVAX that can be delegated to this
validator.
potentialRewards:
description: Estimated rewards for the validator if the validation is successful.
allOf:
- $ref: '#/components/schemas/Rewards'
validationStatus:
type: string
enum:
- active
validatorHealth:
$ref: '#/components/schemas/ValidatorHealthDetails'
geolocation:
nullable: true
description: The geographical location of the validator node, if available.
allOf:
- $ref: '#/components/schemas/Geolocation'
required:
- txHash
- nodeId
- subnetId
- amountStaked
- startTimestamp
- endTimestamp
- stakePercentage
- delegatorCount
- uptimePerformance
- potentialRewards
- validationStatus
- validatorHealth
- geolocation
PendingValidatorDetails:
type: object
properties:
txHash:
type: string
nodeId:
type: string
subnetId:
type: string
amountStaked:
type: string
delegationFee:
type: string
description: >-
The percentage of total estimated delegator rewards allocated to
validator nodes for supporting delegations.
startTimestamp:
type: number
endTimestamp:
type: number
blsCredentials:
description: Present for AddPermissionlessValidatorTx
allOf:
- $ref: '#/components/schemas/BlsCredentials'
validationStatus:
type: string
enum:
- pending
required:
- txHash
- nodeId
- subnetId
- amountStaked
- startTimestamp
- endTimestamp
- validationStatus
RemovedValidatorDetails:
type: object
properties:
txHash:
type: string
nodeId:
type: string
subnetId:
type: string
amountStaked:
type: string
delegationFee:
type: string
description: >-
The percentage of total estimated delegator rewards allocated to
validator nodes for supporting delegations.
startTimestamp:
type: number
endTimestamp:
type: number
blsCredentials:
description: Present for AddPermissionlessValidatorTx
allOf:
- $ref: '#/components/schemas/BlsCredentials'
removeTxHash:
type: string
description: The transaction hash that removed the permissioned subnet validator.
removeTimestamp:
type: number
description: >-
The timestamp of the transaction that removed the permissioned
subnet validator.
validationStatus:
type: string
enum:
- removed
required:
- txHash
- nodeId
- subnetId
- amountStaked
- startTimestamp
- endTimestamp
- removeTxHash
- removeTimestamp
- validationStatus
BlsCredentials:
type: object
properties:
publicKey:
type: string
proofOfPossession:
type: string
required:
- publicKey
- proofOfPossession
Rewards:
type: object
properties:
validationRewardAmount:
type: string
delegationRewardAmount:
type: string
rewardAddresses:
type: array
items:
type: string
rewardTxHash:
type: string
required:
- validationRewardAmount
- delegationRewardAmount
ValidatorHealthDetails:
type: object
properties:
reachabilityPercent:
type: number
description: Percent of requests responded to in last polling.
benchedPChainRequestsPercent:
type: number
description: Percent of requests benched on the P-Chain in last polling.
benchedXChainRequestsPercent:
type: number
description: Percentage of requests benched on the X-Chain in last polling.
benchedCChainRequestsPercent:
type: number
description: Percentage of requests benched on the C-Chain in last polling.
required:
- reachabilityPercent
- benchedPChainRequestsPercent
- benchedXChainRequestsPercent
- benchedCChainRequestsPercent
Geolocation:
type: object
properties:
city:
type: string
description: The name of the validator node.
country:
type: string
description: The city of the validator node.
countryCode:
type: string
description: The country code of the validator node.
latitude:
type: number
description: The latitude of the validator node.
longitude:
type: number
description: The longitude of the validator node.
required:
- city
- country
- countryCode
- latitude
- longitude
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-glacier-api-key
description: >-
Api keys provide higher access to rate limits. To obtain an api key,
sign up for an account at https://avacloud.io/.
````