> ## 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 > Returns an entity's MEV timing-game statistics as a per-day series. Optionally scope to a sub-entity; omit `sub_entity` for the entity-level rows. **Use case guide:** [Compare MEV Timing](/use-cases/compare-mev-timing) shows how to benchmark an entity or sub-entity against the network. **Protocol caveat:** The 1200 ms and 2600 ms timing bands apply to pre-Glamsterdam slots. [Glamsterdam](https://ethereum.org/roadmap/glamsterdam/) introduces ePBS and restructures slot production, so post-fork classifications may change. **Data provenance:** Timing statistics are derived from offchain relay APIs and streams. Relay-reported timestamps, identities, and bid coverage are not independently verifiable from onchain data; coverage gaps or inconsistent reporting can affect results. Results can be filtered by a time range (bucketed to whole UTC days) and are paginated. For an aggregated posture and histogram over an entity (rather than a daily series), use [/api/v2/ethereum/validators/mev-timing-aggregate](/api-reference/ethereum/validators/mev-timing-aggregate) with its entity selector. **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 series contains no days before that date; a time range that falls entirely before it returns an empty result. Data freshness: the most recent ~3 days of daily aggregates are reprocessed and may still change. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/entity/mev-timing 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/entity/mev-timing: post: tags: - Entities summary: 💎 MEV Timing description: > Returns an entity's MEV timing-game statistics as a per-day series. Optionally scope to a sub-entity; omit `sub_entity` for the entity-level rows. **Use case guide:** [Compare MEV Timing](/use-cases/compare-mev-timing) shows how to benchmark an entity or sub-entity against the network. **Protocol caveat:** The 1200 ms and 2600 ms timing bands apply to pre-Glamsterdam slots. [Glamsterdam](https://ethereum.org/roadmap/glamsterdam/) introduces ePBS and restructures slot production, so post-fork classifications may change. **Data provenance:** Timing statistics are derived from offchain relay APIs and streams. Relay-reported timestamps, identities, and bid coverage are not independently verifiable from onchain data; coverage gaps or inconsistent reporting can affect results. Results can be filtered by a time range (bucketed to whole UTC days) and are paginated. For an aggregated posture and histogram over an entity (rather than a daily series), use [/api/v2/ethereum/validators/mev-timing-aggregate](/api-reference/ethereum/validators/mev-timing-aggregate) with its entity selector. **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 series contains no days before that date; a time range that falls entirely before it returns an empty result. Data freshness: the most recent ~3 days of daily aggregates are reprocessed and may still change. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. operationId: GetEntityMevTiming requestBody: $ref: '#/components/requestBodies/entityMevTiming' responses: '200': $ref: '#/components/responses/EntityMevTiming' '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: entityMevTiming: x-go-name: EntityMevTimingRequestBody content: application/json: schema: $ref: '#/components/schemas/EntityMevTimingRequest' example: entity: Lido chain: mainnet responses: EntityMevTiming: description: Successful response. content: application/json: schema: allOf: - $ref: '#/components/schemas/EntityMevTimingDaily.ContainerList' - $ref: '#/components/schemas/PagingRangeTemplate' description: >- Paginated response containing per-day MEV timing statistics for the entity. 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: EntityMevTimingRequest: type: object properties: chain: $ref: '#/components/schemas/Chain' entity: allOf: - $ref: '#/components/schemas/EntityName' description: >- The name of the entity to retrieve MEV timing statistics for (e.g. "Lido", "Coinbase"). Matching is case-sensitive; use the exact name as returned by the entities overview endpoint. sub_entity: $ref: '#/components/schemas/SubEntityName' description: >- Optional sub-entity to scope the statistics. Omit or pass an empty string to get the entity-level aggregate. Matching is case-sensitive; use the exact name as returned by the sub-entities overview endpoint. range: $ref: '#/components/schemas/timeRangeSelectorNullable' cursor: $ref: '#/components/schemas/Cursor' page_size: $ref: '#/components/schemas/PageSize' required: - entity EntityMevTimingDaily.ContainerList: type: object properties: data: type: array items: $ref: '#/components/schemas/EntityMevTimingDaily.Data' required: - data PagingRangeTemplate: type: object properties: paging: $ref: '#/components/schemas/Paging' range: $ref: '#/components/schemas/ResultRange' required: - range Error: type: object properties: error: type: string Chain: type: string enum: - mainnet - hoodi default: mainnet description: The Ethereum chain to query. EntityName: type: string description: The name of the entity (e.g., "Lido", "Coinbase"). SubEntityName: type: string description: The name of the sub-entity. timeRangeSelectorNullable: description: > Specify a time range using either Unix timestamps or epoch numbers. If left null, the API will query the entire available history of the selected validators. nullable: true default: null oneOf: - $ref: '#/components/schemas/timeRangeSelectorTime' - $ref: '#/components/schemas/timeRangeSelectorEpoch' - $ref: '#/components/schemas/timeRangeSelectorSlot' Cursor: type: string description: >- Cursor value for pagination. See our [pagination guide](/api/pagination) for more details. default: '' PageSize: type: integer description: The number of items to return per page. minimum: 1 maximum: 10 default: 10 EntityMevTimingDaily.Data: type: object description: >- Per-entity MEV timing-game statistics aggregated over a single UTC day (`GetEntityMevTiming`). properties: timestamp: allOf: - $ref: '#/components/schemas/timestamp' description: >- Unix timestamp (seconds) of the start of the day (00:00 UTC) this row covers. date: type: string format: date description: >- The day this row covers, as a `YYYY-MM-DD` string (UTC). Human-readable convenience alongside `timestamp`. slots_with_relay_winners: type: integer minimum: 0 description: >- Number of the entity's slots in the day for which a relay bid won (the proposed block came from a relay). Mirrors `slots_with_relay_winners` on the network endpoint — both count slots with an identified winning relay bid. timing_breakdown: $ref: '#/components/schemas/MevTimingBreakdown' median_slot_offset_ms: type: number format: double nullable: true description: >- Median winning-bid slot offset (ms) across the entity's slots with a winning relay bid that day, or `null` if none. histogram: $ref: '#/components/schemas/MevTimingHistogram' required: - timestamp - date - slots_with_relay_winners - timing_breakdown - median_slot_offset_ms - histogram Paging: type: object properties: next_cursor: description: >- Cursor to the next page of results. See our [pagination guide](/api/pagination) for more details. If empty, there are no more pages to fetch. type: string ResultRange: type: object description: > The time span actually covered by the returned results — from the first to the last matching data point — specified in slots, epochs, and Unix timestamps. This reflects the data that was found, not the range that was queried. When no data is found, it falls back to the requested range, or to the full available history if no range was given. For arbitrary (custom) time-range queries the queried range is expanded outward to whole UTC days, so the covered range may be wider than requested. As stated above, the reported range still reflects the data that was actually found — a touched UTC day with no data for the selected validators will not extend it. properties: slot: $ref: '#/components/schemas/SlotRange' epoch: $ref: '#/components/schemas/EpochRange' timestamp: $ref: '#/components/schemas/TimeRange' required: - slot - epoch - timestamp timeRangeSelectorTime: type: object title: Unix Timestamp description: Range provided via Unix timestamp (inclusive) properties: timestamp: $ref: '#/components/schemas/timeRangeStartEnd' required: - timestamp timeRangeSelectorEpoch: type: object title: Epoch description: Range provided via epoch number properties: epoch: $ref: '#/components/schemas/epochRangeStartEnd' required: - epoch timeRangeSelectorSlot: type: object title: Slot description: Range provided via slot number properties: slot: $ref: '#/components/schemas/slotRangeStartEnd' required: - slot timestamp: type: integer minimum: 0 MevTimingBreakdown: type: object description: >- Count of slots in each timing-game band over the covered period, derived from the histogram at the 1200 ms / 2600 ms thresholds (see `MevTimingStatus`). These thresholds apply to pre-Glamsterdam slots and may change for post-fork classifications. properties: on_time_mev: type: integer minimum: 0 description: Slots whose winning bid arrived ≤ 1200 ms after slot start. timing_games: type: integer minimum: 0 description: Slots whose winning bid arrived 1201–2600 ms after slot start. aggressive_tg: type: integer minimum: 0 description: Slots whose winning bid arrived > 2600 ms after slot start. required: - on_time_mev - timing_games - aggressive_tg 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' SlotRange: type: object properties: start: $ref: '#/components/schemas/Slot' end: $ref: '#/components/schemas/Slot' required: - start - end EpochRange: type: object properties: start: $ref: '#/components/schemas/Epoch' end: $ref: '#/components/schemas/Epoch' required: - start - end TimeRange: type: object properties: start: $ref: '#/components/schemas/timestamp' end: $ref: '#/components/schemas/timestamp' required: - start - end timeRangeStartEnd: type: object description: Unix timestamp range (inclusive) properties: start: $ref: '#/components/schemas/timestamp' example: 0 description: Start Unix Timestamp end: $ref: '#/components/schemas/timestamp' example: 2147483647 description: End Unix Timestamp required: - start - end epochRangeStartEnd: type: object description: Epoch range (inclusive) properties: start: $ref: '#/components/schemas/EpochSelector' description: Start Epoch end: $ref: '#/components/schemas/EpochSelector' description: End Epoch required: - start - end slotRangeStartEnd: type: object description: Slot range (inclusive) properties: start: $ref: '#/components/schemas/SlotSelector' description: Start Slot end: $ref: '#/components/schemas/SlotSelector' description: End Slot 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 Slot: type: integer minimum: 0 description: Slot by number. Epoch: type: integer minimum: 0 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' SlotSelector: description: | Specify a slot using one of the following methods. - Slot number - Consensus layer block root - View: "latest", "finalized" oneOf: - $ref: '#/components/schemas/SlotByNumber' - $ref: '#/components/schemas/SlotByConsensusLayerBlockRoot' - $ref: '#/components/schemas/SlotByChainView' default: latest wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ 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 SlotByNumber: title: Number type: object properties: number: $ref: '#/components/schemas/Slot' required: - number SlotByConsensusLayerBlockRoot: title: Root type: object properties: root: $ref: '#/components/schemas/ConsensusLayerBlockRoot' required: - root SlotByChainView: title: View type: object properties: view: allOf: - $ref: '#/components/schemas/ChainView' description: > - "latest": Refers to the most recent slot, which may be subject to reorganization. - "finalized": Refers to the latest slot that has been finalized and is not subject to change. required: - view 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. ConsensusLayerBlockRoot: type: string pattern: ^0x[a-fA-F0-9]{64}$ description: A 32-byte block root represented as a hex string with 0x prefix. 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. ````