> ## Documentation Index > Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt > Use this file to discover all available pages before exploring further. # Epoch > Returns a rolled-up overview of a single consensus layer epoch. In Ethereum, an epoch is a fixed window of consensus layer slots (32 on Ethereum Mainnet) over which validator attestations are aggregated and finality is determined. This endpoint summarizes network-wide activity for the epoch: validator participation, balances, block proposal outcomes, and the protocol events (deposits, withdrawals, exits, slashings) included across its slots. Think of it as a per-epoch starting point: the `slots` range tells you which slots belong to the epoch so you can drill into per-slot detail via [v2/ethereum/slot](/api-reference/ethereum/slot/overview), and the counts point you to the more specific endpoints for each topic. You can query by epoch number, or use "latest" / "finalized" for the most recent or finalized epoch. The "finalized" view can lag the chain's latest finalized epoch by up to one epoch so that every metric of the returned epoch is fully populated. Note: for an epoch whose duties have not yet been fully aggregated (the most recent epochs, whether not-yet-finalized or queried by number just after finalization) the participation- and performance-based fields (`attesting_balance`, `participation_rate`, `attestation_participation`, `sync_participation`, `beaconscore`) are `null` — check `finality` to tell an in-progress epoch apart, and query "finalized" for a complete, stable response. ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/epoch openapi: 3.0.4 info: title: External Service API version: 1.0.3 servers: - url: https://beaconcha.in description: Production API security: - ApiKeyAuth: [] paths: /api/v2/ethereum/epoch: post: tags: - Epoch summary: Epoch description: > Returns a rolled-up overview of a single consensus layer epoch. In Ethereum, an epoch is a fixed window of consensus layer slots (32 on Ethereum Mainnet) over which validator attestations are aggregated and finality is determined. This endpoint summarizes network-wide activity for the epoch: validator participation, balances, block proposal outcomes, and the protocol events (deposits, withdrawals, exits, slashings) included across its slots. Think of it as a per-epoch starting point: the `slots` range tells you which slots belong to the epoch so you can drill into per-slot detail via [v2/ethereum/slot](/api-reference/ethereum/slot/overview), and the counts point you to the more specific endpoints for each topic. You can query by epoch number, or use "latest" / "finalized" for the most recent or finalized epoch. The "finalized" view can lag the chain's latest finalized epoch by up to one epoch so that every metric of the returned epoch is fully populated. Note: for an epoch whose duties have not yet been fully aggregated (the most recent epochs, whether not-yet-finalized or queried by number just after finalization) the participation- and performance-based fields (`attesting_balance`, `participation_rate`, `attestation_participation`, `sync_participation`, `beaconscore`) are `null` — check `finality` to tell an in-progress epoch apart, and query "finalized" for a complete, stable response. operationId: GetEpochOverview requestBody: $ref: '#/components/requestBodies/EpochAndChain' responses: '200': $ref: '#/components/responses/EpochOverview' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/DefaultError' components: requestBodies: EpochAndChain: content: application/json: schema: allOf: - $ref: '#/components/schemas/NamedChain' - $ref: '#/components/schemas/NamedEpochSelector' required: - epoch example: epoch: view: latest chain: mainnet responses: EpochOverview: description: Successful response. content: application/json: schema: $ref: '#/components/schemas/EpochOverview.Container' BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Bad request. Please check your input and try again. Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized. Please provide a valid API key. Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- endpoint not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing. NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: The requested resource was not found. MethodNotAllowed: description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'method not allowed: GET. all public API endpoints use POST.' RateLimitExceeded: description: Rate Limit Exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Rate limit exceeded. Please try again later. InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal server error. please try again later. DefaultError: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: An unexpected error occurred. schemas: NamedChain: type: object properties: chain: $ref: '#/components/schemas/Chain' NamedEpochSelector: type: object properties: epoch: $ref: '#/components/schemas/EpochSelector' required: - epoch EpochOverview.Container: type: object properties: data: $ref: '#/components/schemas/EpochOverview.Data' description: Response containing basic information about the epoch. required: - data Error: type: object properties: error: type: string Chain: type: string enum: - mainnet - hoodi default: mainnet description: The Ethereum chain to query. EpochSelector: description: | Specify an epoch using one of the following methods. - epoch number - View: "latest", "finalized" oneOf: - $ref: '#/components/schemas/EpochByNumber' - $ref: '#/components/schemas/EpochByChainView' EpochOverview.Data: type: object description: > Rolled-up overview of a single consensus layer epoch. An epoch spans a fixed window of consensus layer slots (32 on Ethereum Mainnet) during which validator duties are scheduled and attestations are aggregated. This endpoint summarizes network-wide activity for the epoch and provides the slot range you can use to drill into individual slots via the slot endpoints. properties: epoch: $ref: '#/components/schemas/Epoch' timestamp: description: >- Unix timestamp marking the start of the epoch (the start of its first slot). allOf: - $ref: '#/components/schemas/timestamp' slots: description: > The contiguous range of slot numbers belonging to this epoch, from the first slot to the last slot inclusive. Every slot number in this range exists on the consensus layer; a slot with no block is a missed slot, not a gap. Use these slot numbers with the slot endpoints (e.g. [v2/ethereum/slot](/api-reference/ethereum/slot/overview)) to fetch per-slot detail. allOf: - $ref: '#/components/schemas/SlotRange' sync_committee_period: nullable: true description: > The sync committee period this epoch belongs to. Null for epochs before the Altair hard fork, where sync committees did not yet exist. allOf: - $ref: '#/components/schemas/SyncCommitteePeriod' validators_count: type: integer minimum: 0 description: >- Number of active validators participating in consensus during this epoch. total_validator_balance: description: Sum of the actual balances (in wei) of all validators at this epoch. allOf: - $ref: '#/components/schemas/wei' average_validator_balance: description: >- Mean actual balance (in wei) per validator at this epoch (total_validator_balance / validators_count). allOf: - $ref: '#/components/schemas/wei' total_active_balance: description: >- Total effective balance (in wei) of all validators eligible to attest in this epoch. Used as the denominator when computing participation. allOf: - $ref: '#/components/schemas/wei' attesting_balance: nullable: true description: >- Total effective balance (in wei) of validators whose attestations for this epoch were included with a correct target vote. Used as the numerator when computing participation. Null for the current, not-yet-finalized epoch until its attestations have been aggregated. allOf: - $ref: '#/components/schemas/wei' participation_rate: nullable: true description: >- Fraction of the total active balance that voted correctly in this epoch (attesting_balance / total_active_balance), expressed as a value between 0 and 1. Null for the current, not-yet-finalized epoch until its attestations have been aggregated. allOf: - $ref: '#/components/schemas/percent' proposals: type: object description: > Rollup of block proposal outcomes across the slots of this epoch. Each slot has a single proposal outcome; the fields below mirror the values of the proposal duty status used elsewhere in the API. properties: scheduled: type: integer minimum: 0 description: >- Number of slots whose block proposal is still scheduled and not yet due. Non-zero only for the current or a future epoch. success: type: integer minimum: 0 description: Number of slots with a successfully proposed and included block. missed: type: integer minimum: 0 description: >- Number of slots where the assigned proposer failed to propose a block. orphaned: type: integer minimum: 0 description: >- Number of slots whose proposed block was orphaned (not part of the canonical chain). required: - scheduled - success - missed - orphaned attestation_participation: type: object nullable: true description: >- Network-wide attestation duty participation for this epoch, counted across all validators. Each active validator has exactly one attestation duty per epoch, so these are raw duty counts and complement the effective-balance-weighted participation_rate. Null for the current, not-yet-finalized epoch, and for a recently finalized epoch until its network analytics have been computed (a short lag after finalization). properties: successful: type: integer minimum: 0 description: >- Number of validators whose attestation for this epoch was included. assigned: type: integer minimum: 0 description: Number of validators assigned an attestation duty in this epoch. missed: type: integer minimum: 0 description: >- Number of validators that failed to get an attestation included for this epoch. Since each validator has a single attestation duty per epoch, this is also the count of validators that were effectively offline. required: - successful - assigned - missed sync_participation: type: object nullable: true description: >- Network-wide sync committee participation for this epoch, aggregated over the sync committee's per-slot duties. Null for the current, not-yet-finalized epoch, for a recently finalized epoch until its network analytics have been computed (a short lag after finalization), and for epochs before the Altair hard fork where sync committees did not yet exist. properties: successful: type: integer minimum: 0 description: >- Number of sync committee messages included across the slots of this epoch. assigned: type: integer minimum: 0 description: >- Number of sync committee messages expected across the slots of this epoch. missed: type: integer minimum: 0 description: >- Number of expected sync committee messages that were not included across the slots of this epoch. required: - successful - assigned - missed beaconscore: nullable: true description: >- Network-wide BeaconScore for this epoch — the aggregate effectiveness of all validators at their attestation, proposal, and sync committee duties, as ratios from 0 to 1 where 1 is perfect. Null for the current, not-yet-finalized epoch, and for a recently finalized epoch until its network analytics have been computed (a short lag after finalization). allOf: - $ref: '#/components/schemas/performanceBeaconscore' included_aggregate_count: type: integer minimum: 0 description: >- Total number of attestation aggregates included in the blocks of this epoch. An aggregate can bundle the votes of many validators, so this is unrelated to the per-validator duty counts in attestation_participation. deposits_count: type: integer minimum: 0 description: Total number of validator deposits included in this epoch. withdrawals_count: type: integer minimum: 0 description: Total number of validator withdrawals processed in this epoch. voluntary_exits_count: type: integer minimum: 0 description: Total number of voluntary validator exits included in this epoch. included_slashing_count: type: object description: >- Counts of slashing proofs included in the blocks of this epoch, broken down by the slashed offense type. properties: proposer: type: integer minimum: 0 description: >- Number of proposer slashing proofs included in this epoch (a proposer signing two different blocks for the same slot). attestation: type: integer minimum: 0 description: >- Number of attester slashing proofs included in this epoch (double voting or surround voting). required: - proposer - attestation finality: $ref: '#/components/schemas/FinalityParams' required: - epoch - timestamp - slots - sync_committee_period - validators_count - total_validator_balance - average_validator_balance - total_active_balance - attesting_balance - participation_rate - proposals - attestation_participation - sync_participation - beaconscore - included_aggregate_count - deposits_count - withdrawals_count - voluntary_exits_count - included_slashing_count - finality EpochByNumber: title: Number type: object properties: number: $ref: '#/components/schemas/Epoch' required: - number EpochByChainView: title: View type: object properties: view: allOf: - $ref: '#/components/schemas/ChainView' description: > - "latest": Refers to the most recent epoch, which may not yet be finalized. - "finalized": Refers to the latest epoch that has been finalized and is not subject to change. required: - view Epoch: type: integer minimum: 0 timestamp: type: integer minimum: 0 SlotRange: type: object properties: start: $ref: '#/components/schemas/Slot' end: $ref: '#/components/schemas/Slot' required: - start - end SyncCommitteePeriod: description: > The sync committee period number. Each sync committee period spans 256 epochs (approximately 27.3 hours with 6.4 minute epochs). The first sync committee period (period 290 on Ethereum Mainnet) started at the Altair hard fork on Oct 27, 2021, 10:56:23am UTC (epoch 74240). type: integer minimum: 0 wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ percent: type: number format: float minimum: 0 maximum: 1 performanceBeaconscore: type: object description: >- BeaconScore efficiency metrics for the selected scope and evaluation window. Values are ratios from 0 to 1, where 1 represents perfect duty performance. properties: total: allOf: - $ref: '#/components/schemas/percent' description: >- Overall BeaconScore combining attestation, proposal, and sync committee performance. nullable: true attestation: allOf: - $ref: '#/components/schemas/percent' description: BeaconScore component for attestation performance. nullable: true proposal: allOf: - $ref: '#/components/schemas/percent' description: >- BeaconScore component for proposal performance, normalized to reduce the effect of proposal luck. nullable: true sync_committee: allOf: - $ref: '#/components/schemas/percent' description: BeaconScore component for sync committee performance. nullable: true FinalityParams: type: string description: | Indicates the finality status of the data provided. - Finalized data cannot be changed without slashing at least one-third of all validators, providing strong economic guarantees. - Data marked as not_finalized does not have this guarantee and may still change. enum: - not_finalized - finalized ChainView: type: string enum: - latest - finalized description: > - "latest": Refers to the most recent block, which may be subject to reorganization. - "finalized": Refers to the latest block that has been finalized and is not subject to change. Slot: type: integer minimum: 0 description: Slot by number. securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Authorization header with value: Bearer YOUR_TOKEN. Refer to the [API Keys](/api/overview#api-keys) section to create your API key. ````