> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validationcloud.io/llms.txt
> Use this file to discover all available pages before exploring further.
# /eth/v1/beacon/states/{state_id}/validators
> Get validators from state
```bash title="Mainnet" theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -X GET \
"https://mainnet.ethereum.validationcloud.io/v1//eth/v1/beacon/states/head/validators?status=active" \
-H "Content-Type: application/json"
```
```bash title="Testnet" theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -X GET \
"https://sepolia.ethereum.validationcloud.io/v1//eth/v1/beacon/states/head/validators?status=active" \
-H "Content-Type: application/json"
```
## OpenAPI
````yaml nodeapi/openapi/beacon-node-oapi-v2.json GET /eth/v1/beacon/states/{state_id}/validators
openapi: 3.0.3
info:
title: Eth Beacon Node API
description: >
API specification for the beacon node, which enables users to query and
participate in Ethereum 2.0 phase 0 beacon chain.
All requests by default send and receive JSON, and as such should have
either or both of the "Content-Type: application/json"
and "Accept: application/json" headers. In addition, some requests can
return data in the SSZ format. To indicate that SSZ
data is required in response to a request the header "Accept:
application/octet-stream" should be sent. Note that only a subset
of requests can respond with data in SSZ format; these are noted in each
individual request.
API endpoints are individually versioned. As such, there is no direct
relationship between all v1 endpoints, all v2 endpoints,
_etc._ and no such relationship should be inferred. All JSON responses
return the requested data under a `data` key in the top
level of their response. Additional metadata may or may not be present in
other keys at the top level of the response, dependent
on the endpoint. The rules that require an increase in version number are
as follows:
- no field that is listed in an endpoint shall be removed without an increase in the version number
- no field that is listed in an endpoint shall be altered in terms of format (_e.g._ from a string to an array) without an
increase in the version number
Note that it is possible for a field to be added to an endpoint's data or
metadata without an increase in the version number.
version: v2.3.0 - Eth2Spec v1.1.0
contact:
name: Ethereum Github
url: https://github.com/ethereum/beacon-apis/issues
license:
name: CC0-1.0
url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://mainnet.ethereum.validationcloud.io/v1//
description: Mainnet Beacon API
- url: https://sepolia.ethereum.validationcloud.io/v1//
description: Sepolia Beacon API
security: []
tags:
- name: Beacon
description: Set of endpoints to query beacon chain.
- name: Config
description: Endpoints to query chain configuration, specification, and fork schedules.
- name: Debug
description: Set of endpoints to debug chain and shouldn't be exposed publicly.
- name: Events
description: Set of endpoints to for event subscription.
- name: Node
description: Endpoints to query node related informations
- name: Validator
description: Endpoints intended for validator clients
- name: ValidatorRequiredApi
description: >
Minimal set of endpoints to enable a working validator implementation.
[Checkout validator
flow](https://github.com/ethereum/beacon-APIs/blob/master/validator-flow.md)
to learn how to use this api.
paths:
/eth/v1/beacon/states/{state_id}/validators:
get:
tags:
- Beacon
summary: Get validators from state
description: >
Returns filterable list of validators with their balance, status and
index.
Information will be returned for all indices or public key that match
known validators. If an index or public key does not
match any known validator, no information will be returned but this will
not cause an error. There are no guarantees for the
returned data in terms of ordering; both the index and public key are
returned for each validator, and can be used to confirm
for which inputs a response has been returned.
operationId: getStateValidators
parameters:
- required: true
name: state_id
in: path
example: head
schema:
type: string
description: >
State identifier.
Can be one of: "head" (canonical head in node's view), "genesis",
"finalized", "justified", \, \.
- name: id
description: >-
Either hex encoded public key (any bytes48 with 0x prefix) or
validator index
in: query
required: false
schema:
type: array
maxItems: 30
uniqueItems: true
items:
description: >-
Either hex encoded public key (any bytes48 with 0x prefix) or
validator index
type: string
- name: status
description: >-
[Validator status
specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ)
in: query
required: false
schema:
type: array
uniqueItems: true
items:
allOf:
- description: >
Possible statuses:
- **pending_initialized** - When the first deposit is
processed, but not enough funds are available (or not yet
the end of the first epoch) to get validator into the
activation queue.
- **pending_queued** - When validator is waiting to get
activated, and have enough funds etc. while in the queue,
validator activation epoch keeps changing until it gets to
the front and make it through (finalization is a requirement
here too).
- **active_ongoing** - When validator must be attesting, and
have not initiated any exit.
- **active_exiting** - When validator is still active, but
filed a voluntary request to exit.
- **active_slashed** - When validator is still active, but
have a slashed status and is scheduled to exit.
- **exited_unslashed** - When validator has reached reguler
exit epoch, not being slashed, and doesn't have to attest
any more, but cannot withdraw yet.
- **exited_slashed** - When validator has reached reguler
exit epoch, but was slashed, have to wait for a longer
withdrawal period.
- **withdrawal_possible** - After validator has exited, a
while later is permitted to move funds, and is truly out of
the system.
- **withdrawal_done** - (not possible in phase0, except
slashing full balance) - actually having moved funds away
[Validator status
specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ)
enum:
- pending_initialized
- pending_queued
- active_ongoing
- active_exiting
- active_slashed
- exited_unslashed
- exited_slashed
- withdrawal_possible
- withdrawal_done
example: active_ongoing
- enum:
- active
- pending
- exited
- withdrawal
responses:
'200':
description: Success
content:
application/json:
schema:
title: GetStateValidatorsResponse
type: object
properties:
execution_optimistic:
allOf:
- type: boolean
- example: false
- description: >-
True if the response references an unverified
execution payload. Optimistic information may be
invalidated at a later time. If the field is not
present, assume the False value.
data:
type: array
items:
type: object
properties:
index:
allOf:
- type: string
example: '1'
- description: Index of validator in validator registry.
balance:
allOf:
- type: string
example: '1'
- description: Current validator balance in gwei.
status:
description: >
Possible statuses:
- **pending_initialized** - When the first deposit
is processed, but not enough funds are available (or
not yet the end of the first epoch) to get validator
into the activation queue.
- **pending_queued** - When validator is waiting to
get activated, and have enough funds etc. while in
the queue, validator activation epoch keeps changing
until it gets to the front and make it through
(finalization is a requirement here too).
- **active_ongoing** - When validator must be
attesting, and have not initiated any exit.
- **active_exiting** - When validator is still
active, but filed a voluntary request to exit.
- **active_slashed** - When validator is still
active, but have a slashed status and is scheduled
to exit.
- **exited_unslashed** - When validator has reached
reguler exit epoch, not being slashed, and doesn't
have to attest any more, but cannot withdraw yet.
- **exited_slashed** - When validator has reached
reguler exit epoch, but was slashed, have to wait
for a longer withdrawal period.
- **withdrawal_possible** - After validator has
exited, a while later is permitted to move funds,
and is truly out of the system.
- **withdrawal_done** - (not possible in phase0,
except slashing full balance) - actually having
moved funds away
[Validator status
specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ)
enum:
- pending_initialized
- pending_queued
- active_ongoing
- active_exiting
- active_slashed
- exited_unslashed
- exited_slashed
- withdrawal_possible
- withdrawal_done
example: active_ongoing
validator:
type: object
properties:
pubkey:
type: string
pattern: ^0x[a-fA-F0-9]{96}$
description: >-
The validator's BLS public key, uniquely
identifying them. _48-bytes, hex encoded with 0x
prefix, case insensitive._
example: >-
0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a
withdrawal_credentials:
allOf:
- type: string
example: >-
0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2
pattern: ^0x[a-fA-F0-9]{64}$
- description: Root of withdrawal credentials
effective_balance:
allOf:
- type: string
example: '1'
- description: Balance at stake in Gwei.
slashed:
type: boolean
example: false
description: Was validator slashed (not longer active).
activation_eligibility_epoch:
allOf:
- type: string
example: '1'
- description: When criteria for activation were met.
activation_epoch:
allOf:
- type: string
example: '1'
- description: >-
Epoch when validator activated.
'FAR_FUTURE_EPOCH' if not activated
exit_epoch:
allOf:
- type: string
example: '1'
- description: >-
Epoch when validator exited.
'FAR_FUTURE_EPOCH' if not exited.
withdrawable_epoch:
allOf:
- type: string
example: '1'
- description: >-
When validator can withdraw or transfer
funds. 'FAR_FUTURE_EPOCH' if not defined
'400':
description: Invalid state or validator ID, or status
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
description: >-
Either specific error code in case of invalid request
or http status code
type: number
example: 404
message:
description: Message describing error
type: string
stacktraces:
description: Optional stacktraces, sent when node is in debug mode
type: array
items:
type: string
- example:
code: 400
message: 'Invalid state ID: current'
'404':
description: State not found
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
description: >-
Either specific error code in case of invalid request
or http status code
type: number
example: 404
message:
description: Message describing error
type: string
stacktraces:
description: Optional stacktraces, sent when node is in debug mode
type: array
items:
type: string
- example:
code: 404
message: State not found
'500':
description: Beacon node internal error.
content:
application/json:
schema:
type: object
properties:
code:
description: >-
Either specific error code in case of invalid request or
http status code
type: number
example: 404
message:
description: Message describing error
type: string
stacktraces:
description: Optional stacktraces, sent when node is in debug mode
type: array
items:
type: string
example:
code: 500
message: Internal server error
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.