> ## 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. # 💎 Builder Network Performance > Returns the delivery and settlement record of all external builders together over an evaluation window, next to the proposals whose proposer built the execution payload itself. The top-level fields cover the proposals won by external builders and have the same names and meanings as on [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate), so the record of chosen builders compares field by field with the network's. Self-built proposals count only in `blocks` and `self_built`, never in `blocks_won`, `payload`, `settlement` or `trusted_payment`. The figures are raw counts and amounts, not a score. From the Glamsterdam hard fork on, a proposer accepts a builder's bid and the builder reveals the execution payload later. The bid value is paid from the builder's balance when the chain includes the payload, and also when same-slot attester weight reached the builder-payment quorum although the chain did not include it. A trusted payment is an amount the builder promises to transfer inside the payload; the chain never checks or enforces it, and `trusted_payment.delivered` counts only the payloads checked so far (see `trusted_payment.unchecked_count`). Only finalized slots whose execution payload status is decided count, and the window never reaches before the fork. A missed slot has no proposal and does not count. The window ends at the last such slot, at most the last slot of the epoch before the head; `range` returns the window evaluated, or the requested window with zero counts when no slot of it is decided yet. Bid values and payments are stored in Gwei and returned in wei. Combine this endpoint with others for deeper insights: - The same figures for chosen builders: [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate) - The market share of every curated builder entity: [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities) - The proposals of chosen builders, one row each: [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) - The builder registry, with balances and status: [v2/ethereum/builders](/api-reference/ethereum/builders/overview) **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. > [!WARNING] > > **Experimental.** This endpoint returns data only on chains past the Glamsterdam hard fork. Hoodi forks first; mainnet returns `404` until it forks. The request and response may change before the mainnet release. See [Glamsterdam API](https://docs.beaconcha.in/api/glamsterdam.md). ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/builders/network-performance-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/builders/network-performance-aggregate: post: tags: - Builders summary: 💎 Builder Network Performance description: > Returns the delivery and settlement record of all external builders together over an evaluation window, next to the proposals whose proposer built the execution payload itself. The top-level fields cover the proposals won by external builders and have the same names and meanings as on [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate), so the record of chosen builders compares field by field with the network's. Self-built proposals count only in `blocks` and `self_built`, never in `blocks_won`, `payload`, `settlement` or `trusted_payment`. The figures are raw counts and amounts, not a score. From the Glamsterdam hard fork on, a proposer accepts a builder's bid and the builder reveals the execution payload later. The bid value is paid from the builder's balance when the chain includes the payload, and also when same-slot attester weight reached the builder-payment quorum although the chain did not include it. A trusted payment is an amount the builder promises to transfer inside the payload; the chain never checks or enforces it, and `trusted_payment.delivered` counts only the payloads checked so far (see `trusted_payment.unchecked_count`). Only finalized slots whose execution payload status is decided count, and the window never reaches before the fork. A missed slot has no proposal and does not count. The window ends at the last such slot, at most the last slot of the epoch before the head; `range` returns the window evaluated, or the requested window with zero counts when no slot of it is decided yet. Bid values and payments are stored in Gwei and returned in wei. Combine this endpoint with others for deeper insights: - The same figures for chosen builders: [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate) - The market share of every curated builder entity: [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities) - The proposals of chosen builders, one row each: [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) - The builder registry, with balances and status: [v2/ethereum/builders](/api-reference/ethereum/builders/overview) **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. operationId: GetBuilderNetworkPerformanceAggregate requestBody: $ref: '#/components/requestBodies/builderNetworkPerformanceAggregate' responses: '200': $ref: '#/components/responses/BuilderNetworkPerformanceAggregate' '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: builderNetworkPerformanceAggregate: x-go-name: BuilderNetworkPerformanceAggregateRequestBody content: application/json: schema: $ref: '#/components/schemas/BuilderNetworkPerformanceRequest' example: chain: hoodi range: evaluation_window: 30d responses: BuilderNetworkPerformanceAggregate: description: Successful response. content: application/json: schema: $ref: '#/components/schemas/BuilderNetworkPerformance.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: BuilderNetworkPerformanceRequest: type: object properties: chain: $ref: '#/components/schemas/Chain' range: $ref: '#/components/schemas/NamedBuilderEvaluationWindow' required: - range BuilderNetworkPerformance.Container: type: object description: >- Response containing the delivery and settlement record of all external builders over the evaluation window, next to the self-built proposals. properties: data: $ref: '#/components/schemas/BuilderNetworkPerformance.Data' range: $ref: '#/components/schemas/ResultRange' required: - data - range Error: type: object properties: error: type: string Chain: type: string enum: - mainnet - hoodi default: mainnet description: The Ethereum chain to query. NamedBuilderEvaluationWindow: type: object title: Fixed Window properties: evaluation_window: $ref: '#/components/schemas/BuilderEvaluationWindow' required: - evaluation_window BuilderNetworkPerformance.Data: type: object properties: evaluation_window: $ref: '#/components/schemas/BuilderEvaluationWindow' blocks: type: integer description: >- Canonical proposals in the window, `blocks_won` plus `self_built.blocks`. A missed slot has no proposal and does not count. winning_builder_count: type: integer description: >- Builder public keys that won at least one proposal in the window. A proposal whose builder is not in beaconcha.in's copy of the registry counts in `blocks_won` but adds no builder here. blocks_won: type: integer description: >- Canonical proposals in the window whose accepted bid an external builder signed, including those whose execution payload the chain did not include. Self-built proposals never count. bid_value_total: allOf: - $ref: '#/components/schemas/wei' description: >- Summed value of the accepted bids of external builders. The chain stores bid values in Gwei; they are returned in wei. example: '10483251907000000000000' bid_value_max: nullable: true allOf: - $ref: '#/components/schemas/wei' description: >- Highest value of an accepted bid of an external builder. Null when `blocks_won` is `0`. payload: allOf: - $ref: '#/components/schemas/BuilderPerformance.Payload' description: >- What happened to the execution payloads of the proposals won by external builders. `full` plus `empty` is `blocks_won`. settlement: allOf: - $ref: '#/components/schemas/BuilderPerformance.Settlement' description: >- Whether the chain paid the values of the accepted bids of external builders to the proposers. The counts add up to `blocks_won`. trusted_payment: allOf: - $ref: '#/components/schemas/BuilderPerformance.TrustedPayment' description: >- The trusted execution payments that the accepted bids of external builders promised. A self-built bid may also promise one; it is not counted here. self_built: $ref: '#/components/schemas/BuilderNetworkPerformance.SelfBuilt' required: - evaluation_window - blocks - winning_builder_count - blocks_won - bid_value_total - bid_value_max - payload - settlement - trusted_payment - self_built 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 the response is `200` but no data is found, it falls back to the requested range, or to the full available history if no range was given. Some endpoints answer `404` instead when no data is found. 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 BuilderEvaluationWindow: type: string enum: - 24h - 7d - 30d - 90d - all_time x-enum-varnames: - BuilderWindow24h - BuilderWindow7d - BuilderWindow30d - BuilderWindow90d - BuilderWindowAllTime example: 30d description: > The window to aggregate the proposals over. Only finalized slots count whose payload status is decided, which means it is no longer `pending` because the chain has decided whether it included the payload. The window ends at the last such slot, at most at the last slot of the epoch before the head, so it moves every epoch (~6.4 minutes). It starts no earlier than the Glamsterdam hard fork. - `24h`: Last 24 hours (rolling) - `7d`: Last 7 days (rolling) - `30d`: Last 30 days (rolling) - `90d`: Last 90 days (rolling) - `all_time`: Since the Glamsterdam hard fork wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ example: '32000000000000000000' BuilderPerformance.Payload: type: object description: >- What happened to the execution payloads of the proposals won. `full` plus `empty` is the number of proposals won; `withheld`, `skipped` and `no_verdict` split `empty` by the reasons of `EmptyReason`. properties: full: type: integer description: Proposals whose execution payload the chain included. empty: type: integer description: Proposals whose execution payload the chain did not include. withheld: type: integer description: >- Empty payloads for which more than half of the payload timeliness committee's positions voted that the payload was not present by the payload deadline. The chain does not distinguish a late payload from one never revealed. skipped: type: integer description: >- Empty payloads for which more than half of the committee voted that the payload was present in time, yet the next canonical block did not build on it. This is not always the builder's doing, as its blob data may have arrived late. no_verdict: type: integer description: >- Empty payloads for which neither side of the committee has a majority, or no block at the next slot could carry the votes. required: - full - empty - withheld - skipped - no_verdict BuilderPerformance.Settlement: type: object description: >- Whether the chain paid the values of the accepted bids to the proposers, with the meanings of `BuilderPaymentSettlement`. The chain pays a bid's value from the builder's balance when it includes the payload. When it does not include the payload, it still pays if enough of the slot's attesters voted for the block (the builder-payment quorum), so whether a missing payload is paid depends on those attesters, not on the builder. The counts of this object add up to `blocks_won`. Values are returned in wei. properties: paid: type: integer description: >- Bids whose value the chain paid as a builder-payment withdrawal. A withheld payload is paid too when same-slot attester weight reached the builder-payment quorum. paid_value: allOf: - $ref: '#/components/schemas/wei' description: Summed value of the `paid` bids. forfeited: type: integer description: >- Bids whose value the chain did not pay, because it did not include the payload and same-slot attester weight stayed below the builder-payment quorum. forfeited_value: allOf: - $ref: '#/components/schemas/wei' description: Summed value of the `forfeited` bids. pending: type: integer description: >- Bids with a value whose payment is not decided yet, or is decided and its withdrawal has not been found on chain yet. pending_value: allOf: - $ref: '#/components/schemas/wei' description: Summed value of the `pending` bids. void_slashed: type: integer description: >- Bids whose value the chain did not pay, because the proposer was slashed while the payment was still pending. ambiguous: type: integer description: >- Bids for which we could not determine which payment, if any, discharged them. no_payment: type: integer description: >- Bids with a value of `0`, so the chain has nothing to pay. A trusted payment may or may not be promised; see `trusted_payment`. required: - paid - paid_value - forfeited - forfeited_value - pending - pending_value - void_slashed - ambiguous - no_payment BuilderPerformance.TrustedPayment: type: object description: >- The trusted execution payments that the accepted bids promised, amounts the builder transfers to the bid's fee recipient inside the payload. The chain never checks or enforces them. Values are returned in wei. properties: bid_count: type: integer description: Accepted bids that promised a trusted payment. promised: allOf: - $ref: '#/components/schemas/wei' description: Summed trusted payment that these bids promised. delivered: allOf: - $ref: '#/components/schemas/wei' description: >- Summed part of the promises found delivered to the bid's fee recipient inside the payload, capped at each bid's promise, the sum of `execution_payload.trusted_payment_paid` over the proposals of the same builders and window on [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots), counting only those whose payload status is decided, up to `range.end`. A delivery counts transfers to the fee recipient from any sender, and the payload's priority fees when its coinbase is the fee recipient. A payload the chain did not include delivered nothing. unchecked_count: type: integer description: >- Bids among `bid_count` whose included payload has not been checked for the delivery yet. Their deliveries are missing from `delivered`. required: - bid_count - promised - delivered - unchecked_count BuilderNetworkPerformance.SelfBuilt: type: object description: >- The proposals whose proposer built the execution payload itself instead of accepting an external builder's bid. They have no bid value to pay, and none of them counts in `blocks_won`, `payload`, `settlement` or `trusted_payment`. properties: blocks: type: integer description: >- Canonical proposals in the window whose proposer built the execution payload itself. payload: allOf: - $ref: '#/components/schemas/BuilderPerformance.Payload' description: >- What happened to the self-built execution payloads. `full` plus `empty` is `self_built.blocks`. The reasons are the same as for external builders, with the proposer in the builder's place, so a `skipped` self-built payload is one the proposer revealed in time that the next canonical block did not build on, which is not always the proposer's doing either. required: - blocks - payload 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 Slot: type: integer minimum: 0 description: Slot by number. Epoch: type: integer minimum: 0 timestamp: type: integer minimum: 0 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.