> ## 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.

# Network MEV Timing

> Returns network-wide MEV timing-game statistics as a per-day series. Each day carries the slot counts, a timing breakdown, the median slot offset, and the full histogram.

Results can be filtered by a time range (bucketed to whole UTC days) and are paginated. Use `min_slots_per_day` to exclude sparsely-covered days.

**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.




## OpenAPI

````yaml /v3/bundled.yaml post /api/v2/ethereum/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/mev-timing:
    post:
      tags:
        - Network
      summary: Network MEV Timing
      description: >
        Returns network-wide MEV timing-game statistics as a per-day series.
        Each day carries the slot counts, a timing breakdown, the median slot
        offset, and the full histogram.


        Results can be filtered by a time range (bucketed to whole UTC days) and
        are paginated. Use `min_slots_per_day` to exclude sparsely-covered days.


        **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.
      operationId: GetNetworkMevTiming
      requestBody:
        $ref: '#/components/requestBodies/networkMevTiming'
      responses:
        '200':
          $ref: '#/components/responses/NetworkMevTiming'
        '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:
    networkMevTiming:
      x-go-name: NetworkMevTimingRequestBody
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NetworkMevTimingRequest'
          example:
            chain: mainnet
  responses:
    NetworkMevTiming:
      description: Successful response.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/MevTimingDaily.ContainerList'
              - $ref: '#/components/schemas/PagingRangeTemplate'
            description: >-
              Paginated response containing per-day network-wide MEV timing
              statistics.
    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:
    NetworkMevTimingRequest:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        range:
          $ref: '#/components/schemas/timeRangeSelectorNullable'
        min_slots_per_day:
          type: integer
          minimum: 0
          default: 100
          description: >-
            Minimum number of slots with relay data a day must have to be
            included in the results. Filters out sparsely-covered days. Defaults
            to 100.
        cursor:
          $ref: '#/components/schemas/Cursor'
        page_size:
          $ref: '#/components/schemas/PageSize'
    MevTimingDaily.ContainerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MevTimingDaily.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.
    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
    MevTimingDaily.Data:
      type: object
      description: >-
        Network-wide MEV timing-game statistics aggregated over a single UTC day
        (`GetNetworkMevTiming`).
      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:
          type: integer
          minimum: 0
          description: >-
            Number of slots in the day for which at least one relay bid was
            recorded.
        slots_with_relay_winners:
          type: integer
          minimum: 0
          description: >-
            Number of slots in the day for which a relay bid won (the proposed
            block came from a relay).
        slots_without_relay:
          type: integer
          minimum: 0
          description: Number of slots in the day for which no relay bid was recorded.
        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 day's slots with a
            winning relay bid, or `null` if none.
        histogram:
          $ref: '#/components/schemas/MevTimingHistogram'
      required:
        - timestamp
        - date
        - slots_with_relay
        - slots_with_relay_winners
        - slots_without_relay
        - 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 range of data covered by the results, specified in slots, epochs,
        and Unix timestamps.
      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`).
      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:
          $ref: '#/components/schemas/ChainView'
      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:
          $ref: '#/components/schemas/ChainView'
      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.

````