> ## 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. # MEV Timing Aggregate > Returns the overall MEV timing posture and histogram for a set of validators over a fixed evaluation window. The validator set may be selected by identifiers, dashboard, withdrawal/deposit address, or entity/sub-entity. Currently only the `180d` rolling window is available (see `evaluation_window`). **Note:** MEV relay and timing data is only available on mainnet at this time. **History:** Relay bid collection began on 2024-06-03 (UTC). The evaluation window only reflects data from that date onward. Data freshness: validator timing profiles are rebuilt nightly over a rolling 180-day window. ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/validators/mev-timing-aggregate 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/validators/mev-timing-aggregate: post: tags: - Validator summary: MEV Timing Aggregate description: > Returns the overall MEV timing posture and histogram for a set of validators over a fixed evaluation window. The validator set may be selected by identifiers, dashboard, withdrawal/deposit address, or entity/sub-entity. Currently only the `180d` rolling window is available (see `evaluation_window`). **Note:** MEV relay and timing data is only available on mainnet at this time. **History:** Relay bid collection began on 2024-06-03 (UTC). The evaluation window only reflects data from that date onward. Data freshness: validator timing profiles are rebuilt nightly over a rolling 180-day window. operationId: GetValidatorMevTimingAggregate requestBody: $ref: '#/components/requestBodies/validatorMevTimingAggregate' responses: '200': $ref: '#/components/responses/ValidatorMevTiming' '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: validatorMevTimingAggregate: content: application/json: schema: $ref: '#/components/schemas/ValidatorMevTimingRequest' example: validator: validator_identifiers: - 5 - 6 evaluation_window: 180d chain: mainnet responses: ValidatorMevTiming: description: Successful response. content: application/json: schema: $ref: '#/components/schemas/ValidatorMevTiming.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: ValidatorMevTimingRequest: type: object properties: chain: $ref: '#/components/schemas/Chain' validator: $ref: '#/components/schemas/validatorsSelector' evaluation_window: $ref: '#/components/schemas/MevEvaluationWindow' required: - validator ValidatorMevTiming.Container: type: object properties: data: $ref: '#/components/schemas/ValidatorMevTiming.Data' description: >- Response containing the aggregated MEV timing posture of the selected validators. required: - data Error: type: object properties: error: type: string Chain: type: string enum: - mainnet - hoodi default: mainnet description: The Ethereum chain to query. validatorsSelector: description: >- Free selectors available to all users: - validator_identifiers: One or more validator indices or public keys to filter by. - dashboard_id: Your beaconcha.in dashboard ID (requires a free account). **Premium selectors** for Scale & Enterprise plans (https://beaconcha.in/pricing): - withdrawal: The validator's withdrawal credential or the Ethereum wallet address used for withdrawals. - deposit_address: The Ethereum wallet address used for the validator's deposit. - entity: The name of the assigned entity (e.g., "Lido", "Coinbase"). Optionally include `sub_entity` for more specific filtering. Matching is case-sensitive. Note: The set of validators matched by `deposit_address` and `withdrawal` selectors is updated once per epoch (~6.4 minutes). Newly deposited validators may take up to one epoch to appear in query results. Note: The set of validators matched by `entity` selector is updated once per day. oneOf: - $ref: '#/components/schemas/ValidatorsByIdentifiers' - $ref: '#/components/schemas/ValidatorsByDashboard' - $ref: '#/components/schemas/ValidatorsByDeposit' - $ref: '#/components/schemas/ValidatorsByWithdrawal' - $ref: '#/components/schemas/ValidatorsByEntity' MevEvaluationWindow: type: string enum: - 180d default: 180d example: 180d description: > The evaluation window for aggregating validator MEV timing metrics. Currently only `180d` (a rolling 180-day window) is available. - `180d`: Rolling 180-day window. ValidatorMevTiming.Data: type: object description: >- Aggregated MEV timing posture for the selected validator set over the evaluation window. properties: timing_label: $ref: '#/components/schemas/MevTimingLabel' histogram: $ref: '#/components/schemas/MevTimingHistogram' evaluation_window: $ref: '#/components/schemas/MevEvaluationWindow' required: - timing_label - histogram - evaluation_window ValidatorsByIdentifiers: type: object title: Indices/Pubkeys properties: validator_identifiers: $ref: '#/components/schemas/validatorIndexPublicKeys' required: - validator_identifiers ValidatorsByDashboard: type: object title: Dashboard properties: dashboard_id: $ref: '#/components/schemas/dashboardID' group_id: $ref: '#/components/schemas/dashboardGroupID' required: - dashboard_id ValidatorsByDeposit: type: object title: 💎 Deposit properties: deposit_address: $ref: '#/components/schemas/ExecutionLayerAddress' required: - deposit_address ValidatorsByWithdrawal: type: object title: 💎 Withdrawal properties: withdrawal: $ref: '#/components/schemas/AddressOrCredential' required: - withdrawal ValidatorsByEntity: type: object title: 💎 Entity description: > Select validators by their assigned entity (e.g., staking provider) and optionally a sub-entity. Entity and sub-entity names are matched exactly and are case-sensitive. properties: entity: type: string description: > The name of the entity to filter validators by (e.g., "Lido", "Coinbase"). Matching is case-sensitive; use the exact name as returned by the entities overview endpoint. sub_entity: type: string description: > Optional sub-entity name to further filter validators within the entity. Matching is case-sensitive; use the exact name as returned by the sub-entities overview endpoint. required: - entity MevTimingLabel: type: object description: Aggregated timing-game posture over a set of slots. properties: status: $ref: '#/components/schemas/MevTimingStatus' median_slot_offset_ms: type: number format: double nullable: true description: >- Median slot offset (ms relative to slot start) across the aggregated slots, or `null` if no slots had a winning relay bid. total_count: type: integer minimum: 0 description: >- Total number of slots with a winning relay bid that contributed to this summary. required: - status - median_slot_offset_ms - total_count MevTimingHistogram: type: array description: >- Distribution of winning-bid slot offsets across 22 fixed buckets, in ascending order. The first bucket covers all offsets below 0 ms, followed by 20 buckets in 200 ms steps from 0 to 3800 ms, and a final bucket for all offsets at or above 4000 ms. items: $ref: '#/components/schemas/MevTimingBucket' validatorIndexPublicKeys: description: > An array containing either validator indices or public keys. Index and public key can be mixed in the same array. Subscribed users (Hobbyist, Business, and Scale tiers) can include up to 100 entries; free trial users and legacy subscription users (Sapphire, Emerald, Diamond) are limited to 20. type: array items: $ref: '#/components/schemas/validatorIndexPublicKey' minItems: 1 maxItems: 100 dashboardID: description: > beaconcha.in dashboard ID. You can find your dashboard ID in the URL of your dashboard page on beaconcha.in (e.g., https://beaconcha.in/dashboard/12345). type: integer x-go-type: '*int' minimum: 0 dashboardGroupID: description: >- Optional beaconcha.in dashboard group ID. If no group ID is provided, all validators in the dashboard are considered. type: integer minimum: 0 nullable: true ExecutionLayerAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: A standard Ethereum address (20-byte hex string with 0x prefix). AddressOrCredential: type: string pattern: ^(0x)?[0-9a-fA-F]{40}$|^(0x)?0[012][0-9a-fA-F]{62}$ description: > Either an execution layer address (20-byte hex string with 0x prefix) or a full 32-byte withdrawal credential. MevTimingStatus: type: string enum: - on_time_mev - timing_games - aggressive_tg - no_mev - unknown - pending x-enum-varnames: - MevTimingStatusOnTimeMev - MevTimingStatusTimingGames - MevTimingStatusAggressiveTg - MevTimingStatusNoMev - MevTimingStatusUnknown - MevTimingStatusPending example: timing_games description: > Classification of a block's MEV timing behaviour, derived from how long after the slot start the winning relay bid arrived. - `on_time_mev`: winning bid arrived ≤ 1200 ms after slot start — MEV was captured without delaying the proposal. - `timing_games`: winning bid arrived 1201–2600 ms after slot start — the proposer delayed to capture more MEV. - `aggressive_tg`: winning bid arrived > 2600 ms after slot start — aggressive timing games with higher orphan risk. - `no_mev`: no relay bids were observed for this slot at all — the block was built locally (or by a proposer not registered with any tracked relay). - `unknown`: relay bids were observed for this slot, but the winning payload could not be identified — either our periodic relay polling missed it, or the slot predates relay bid collection. The underlying block may still be an MEV block; `unknown` is not evidence either way. - `pending`: the slot is newer than the latest aggregated slot, so its timing outcome has not been computed yet. Retry once relay data catches up (per-slot statistics lag the chain head by roughly 4 hours). MevTimingBucket: type: object description: >- A single bar of the timing histogram. Buckets are 200 ms wide. The first bucket covers all offsets below 0 ms; the last covers all offsets at or above 4000 ms (reported with an upper bound of 4200 ms). properties: slot_offset_ms_min: type: integer description: >- Inclusive lower bound of the bucket, in milliseconds relative to slot start. slot_offset_ms_max: type: integer description: >- Exclusive upper bound of the bucket, in milliseconds relative to slot start. count: type: integer minimum: 0 description: Number of slots whose winning bid offset falls in this bucket. max_value: allOf: - $ref: '#/components/schemas/wei' nullable: true description: >- Highest winning bid value observed in this bucket, or `null` if the bucket is empty. required: - slot_offset_ms_min - slot_offset_ms_max - count - max_value validatorIndexPublicKey: oneOf: - $ref: '#/components/schemas/validatorIndex' - $ref: '#/components/schemas/validatorPublicKey' wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ validatorIndex: description: Validator Index type: integer minimum: 0 validatorPublicKey: type: string description: Public key of a validator pattern: ^0x[a-fA-F0-9]{96}$ 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. ````