---
title: "💎 MEV Timing"
method: POST
path: "/api/v2/ethereum/entity/mev-timing"
tags: ["Entities"]
---

# 💎 MEV Timing

`POST /api/v2/ethereum/entity/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.

## Request body

- EntityMevTimingRequest
  - `chain` 'mainnet' | 'hoodi' — The Ethereum chain to query.
  - `entity` string, required — The name of the entity (e.g., "Lido", "Coinbase").
  - `sub_entity` string — The name of the sub-entity.
  - `range` union — 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.
    - TimeRangeSelectorTime — Range provided via Unix timestamp (inclusive)
      - `timestamp` TimeRangeStartEnd, required — Unix timestamp range (inclusive)
        - `start` integer, required
        - `end` integer, required
    - TimeRangeSelectorEpoch — Range provided via epoch number
      - `epoch` EpochRangeStartEnd, required — Epoch range (inclusive)
        - `start` union, required — Specify an epoch using one of the following methods. - epoch number - View: "latest", "finalized"
          - EpochByNumber
            - `number` integer, required
          - EpochByChainView
            - `view` 'latest' | 'finalized', required — - "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.
        - `end` union, required — Specify an epoch using one of the following methods. - epoch number - View: "latest", "finalized"
          - EpochByNumber
            - `number` integer, required
          - EpochByChainView
            - `view` 'latest' | 'finalized', required — - "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.
    - TimeRangeSelectorSlot — Range provided via slot number
      - `slot` SlotRangeStartEnd, required — Slot range (inclusive)
        - `start` union — Specify a slot using one of the following methods. - Slot number - Consensus layer block root - View: "latest", "finalized"
          - SlotByNumber
            - `number` integer, required — Slot by number.
          - SlotByConsensusLayerBlockRoot
            - `root` string, required — A 32-byte block root represented as a hex string with 0x prefix.
          - SlotByChainView
            - `view` 'latest' | 'finalized', required — - "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.
        - `end` union — Specify a slot using one of the following methods. - Slot number - Consensus layer block root - View: "latest", "finalized"
          - SlotByNumber
            - `number` integer, required — Slot by number.
          - SlotByConsensusLayerBlockRoot
            - `root` string, required — A 32-byte block root represented as a hex string with 0x prefix.
          - SlotByChainView
            - `view` 'latest' | 'finalized', required — - "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.
  - `cursor` string — Cursor value for pagination. See our [pagination guide](/api/pagination) for more details.
  - `page_size` integer — The number of items to return per page.

## Response `200`

Successful response.

- object — Paginated response containing per-day MEV timing statistics for the entity.
  - `data` EntityMevTimingDailyData[], required
    - `timestamp` integer, required
    - `date` string, date, required — The day this row covers, as a `YYYY-MM-DD` string (UTC). Human-readable convenience alongside `timestamp`.
    - `slots_with_relay_winners` integer, required — 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` MevTimingBreakdown, required — 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.
      - `on_time_mev` integer, required — Slots whose winning bid arrived ≤ 1200 ms after slot start.
      - `timing_games` integer, required — Slots whose winning bid arrived 1201–2600 ms after slot start.
      - `aggressive_tg` integer, required — Slots whose winning bid arrived > 2600 ms after slot start.
    - `median_slot_offset_ms` number, double, nullable, required — Median winning-bid slot offset (ms) across the entity's slots with a winning relay bid that day, or `null` if none.
    - `histogram` MevTimingBucket[], required — 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.
      - `slot_offset_ms_min` integer, required — Inclusive lower bound of the bucket, in milliseconds relative to slot start.
      - `slot_offset_ms_max` integer, required — Exclusive upper bound of the bucket, in milliseconds relative to slot start.
      - `count` integer, required — Number of slots whose winning bid offset falls in this bucket.
      - `max_value` string, required — Amount in wei (1 ETH = 10^18 wei)
  - `paging` Paging
    - `next_cursor` string — 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.
  - `range` ResultRange, required — The range of data covered by the results, specified in slots, epochs, and Unix timestamps.
    - `slot` SlotRange, required
      - `start` integer, required — Slot by number.
      - `end` integer, required — Slot by number.
    - `epoch` EpochRange, required
      - `start` integer, required
      - `end` integer, required
    - `timestamp` TimeRange, required
      - `start` integer, required
      - `end` integer, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `405` — Method Not Allowed
- `429` — Rate Limit Exceeded
- `500` — Internal Server Error
- `default` — An unexpected error response.

---

[API](https://skmtc.net/beaconcha/apis/external-service-api.md) · [All operations](https://skmtc.net/beaconcha/apis/external-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/beaconcha/external-service-api/versions/ad26ad970b4e/schema)