> ## 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 Performance Aggregate > Returns the delivery and settlement record of the selected builders over an evaluation window: the proposals whose accepted bid they won, what happened to the execution payloads, whether the chain paid the bid values, and how much of the promised trusted payments the payloads delivered. 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. Only finalized slots whose execution payload status is decided count, and the window never reaches before the fork. 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 when no slot of it is decided yet. A builder that won nothing in the window returns zero counts. Bid values and payments are stored in Gwei and returned in wei. Combine this endpoint with others for deeper insights: - The proposals behind these figures, one row each: [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) with the same `builder` selector - The registry entries of the builders, with balances and status: [v2/ethereum/builders](/api-reference/ethereum/builders/overview) - The market share of every curated builder entity: [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities) **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/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/performance-aggregate: post: tags: - Builders summary: 💎 Builder Performance Aggregate description: > Returns the delivery and settlement record of the selected builders over an evaluation window: the proposals whose accepted bid they won, what happened to the execution payloads, whether the chain paid the bid values, and how much of the promised trusted payments the payloads delivered. 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. Only finalized slots whose execution payload status is decided count, and the window never reaches before the fork. 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 when no slot of it is decided yet. A builder that won nothing in the window returns zero counts. Bid values and payments are stored in Gwei and returned in wei. Combine this endpoint with others for deeper insights: - The proposals behind these figures, one row each: [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) with the same `builder` selector - The registry entries of the builders, with balances and status: [v2/ethereum/builders](/api-reference/ethereum/builders/overview) - The market share of every curated builder entity: [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities) **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. operationId: GetBuilderPerformanceAggregate requestBody: $ref: '#/components/requestBodies/builderPerformanceAggregate' responses: '200': $ref: '#/components/responses/BuilderPerformanceAggregate' '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: builderPerformanceAggregate: x-go-name: BuilderPerformanceAggregateRequestBody content: application/json: schema: $ref: '#/components/schemas/BuilderPerformanceRequest' example: chain: hoodi builder: builder_index: 1889 range: evaluation_window: 30d responses: BuilderPerformanceAggregate: description: Successful response. content: application/json: schema: $ref: '#/components/schemas/BuilderPerformance.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: BuilderPerformanceRequest: type: object properties: chain: $ref: '#/components/schemas/Chain' builder: $ref: '#/components/schemas/buildersSelector' range: $ref: '#/components/schemas/NamedBuilderEvaluationWindow' required: - builder - range BuilderPerformance.Container: type: object description: >- Response containing the delivery and settlement record of the selected builders over the evaluation window. properties: data: $ref: '#/components/schemas/BuilderPerformance.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. buildersSelector: description: > Select builders by one of these options. Every endpoint that uses this selector requires a Scale or Enterprise plan: - builder_pubkey: One builder, by its public key, as in `execution_payload.builder_pubkey`. The best way to follow one builder over time. - builder_index: The builder that holds this index now. To select the builder of a past slot, use that slot's `builder_pubkey`. - builder_execution_address: Every builder that withdraws to this execution layer address. Use it for all the builders of one operator. - builder_entity: Every builder that withdraws to an address that beaconcha.in curated under this name. Optionally include `builder_sub_entity`. Matching is case-sensitive. Note: When a builder exits and withdraws its whole balance, the chain gives its index to the next new builder, so one index can name different builders over time. Every option therefore resolves to builder public keys, and a proposal counts for a builder only from the epoch it took the index until the epoch the next builder took it. The builder registry exists from the Glamsterdam hard fork on. An option that matches no builder returns 404. A builder that matches but has nothing in the result returns an empty list or zero counts, not 404. oneOf: - $ref: '#/components/schemas/BuildersByPubkey' - $ref: '#/components/schemas/BuildersByIndex' - $ref: '#/components/schemas/BuildersByExecutionAddress' - $ref: '#/components/schemas/BuildersByEntity' NamedBuilderEvaluationWindow: type: object title: Fixed Window properties: evaluation_window: $ref: '#/components/schemas/BuilderEvaluationWindow' required: - evaluation_window BuilderPerformance.Data: type: object properties: evaluation_window: $ref: '#/components/schemas/BuilderEvaluationWindow' builder_count: type: integer description: Builder public keys that the selector matched. winning_builder_count: type: integer description: >- Builder public keys among `builder_count` that won at least one proposal in the window. blocks_won: type: integer description: >- Canonical proposals in the window whose accepted bid a selected builder signed while it held the bid's builder index, including those whose execution payload the chain did not include. Self-built payloads never count. bid_value_total: allOf: - $ref: '#/components/schemas/wei' description: >- Summed value of the accepted bids. The chain stores bid values in Gwei; they are returned in wei. bid_value_max: nullable: true allOf: - $ref: '#/components/schemas/wei' description: Highest value of an accepted bid. Null when `blocks_won` is `0`. payload: $ref: '#/components/schemas/BuilderPerformance.Payload' settlement: $ref: '#/components/schemas/BuilderPerformance.Settlement' trusted_payment: $ref: '#/components/schemas/BuilderPerformance.TrustedPayment' required: - evaluation_window - builder_count - winning_builder_count - blocks_won - bid_value_total - bid_value_max - payload - settlement - trusted_payment 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 BuildersByPubkey: type: object title: Builder Public Key description: >- Select a builder by its public key in the beacon chain's builder registry. Use the key, not the builder index, to follow a builder over time. The chain gives the index of a builder that has exited and withdrawn its balance to the next new builder, and a builder that registers again with the same key can get a different index. The key matches every period in which the builder was registered. properties: builder_pubkey: $ref: '#/components/schemas/BuilderPublicKey' required: - builder_pubkey BuildersByIndex: type: object title: Builder Index description: >- Select the builder that holds this index now, with its full history, as `builder_pubkey` would. An index passes to a new builder after its builder exits and withdraws, so an index from an old slot may now name someone else. For the builder of a past slot, pass that slot's `execution_payload.builder_pubkey` from 💎 [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) or [v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots) instead. properties: builder_index: $ref: '#/components/schemas/BuilderIndex' required: - builder_index BuildersByExecutionAddress: type: object title: 💎 Builder Execution Address description: >- Select every builder whose entry in the beacon chain's builder registry names this execution layer address for its withdrawals. One address can belong to many builders. The address comes from the deposit that registers the builder and does not change while that registration lasts. Anyone can register a builder with any withdrawal address, so a match does not prove that the owner of the address runs the builder. properties: builder_execution_address: allOf: - $ref: '#/components/schemas/ExecutionLayerAddress' example: '0x8f2e4c6a91b3d5e7f0a2c4e6b8d0f1a3c5e7b9d2' description: >- Execution layer address that a builder's registry entry names for its withdrawals. required: - builder_execution_address BuildersByEntity: type: object title: 💎 Builder Entity description: >- Select every builder whose registry entry withdraws to an execution layer address that beaconcha.in curated under this builder entity name, optionally only the addresses of one sub-entity. Names come from [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities). A name without a registered builder returns 404. Builder entity labels may take a few days after a chain's Glamsterdam hard fork to settle, while we observe how builders operate in the first days; until then a name can return 404 because no address carries it yet. properties: builder_entity: $ref: '#/components/schemas/BuilderEntityName' builder_sub_entity: allOf: - $ref: '#/components/schemas/SubEntityName' description: >- Optional sub-entity of `builder_entity`. Omit it or pass an empty string to select the whole entity. Matching is case-sensitive. required: - builder_entity 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 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 BuilderPublicKey: type: string pattern: ^0x[a-fA-F0-9]{96}$ example: >- 0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3 description: >- BLS public key of a builder in the beacon chain's builder registry, which exists from the Glamsterdam hard fork on. The registry is separate from the builder keys that relays report, such as on [v2/ethereum/block/mev-bids](/api-reference/ethereum/block/mev-bids); a relay-reported key matches only if that builder also registered it on chain. BuilderIndex: type: integer minimum: 0 example: 1889 maximum: 1099511627775 description: >- Index of a builder in the beacon chain's builder registry, which exists from the Glamsterdam hard fork on. Always below 2^40 (1099511627776). A builder payment withdrawal on chain carries the builder index plus 2^40 (`BUILDER_INDEX_FLAG`) as its validator index, so subtract 2^40 before you pass it here. When a builder exits and withdraws its whole balance, the chain gives its index to the next new builder, so one index can name different builders over time. ExecutionLayerAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: A standard Ethereum address (20-byte hex string with 0x prefix). example: '0x388C818CA8B9251b393131C08a736A67ccB19297' BuilderEntityName: type: string example: Titan description: >- Curated name of a builder operator, such as a block builder or a relay. Builder entity names share one namespace with staking entity names, so one company has one name, and the same name can stand for a staking entity in a `validator` selector and for a builder operator in a `builder` selector. A relay's name ends in " relay", so a relay never shares an entity with a builder that the same company runs. Matching is case-sensitive. SubEntityName: type: string description: The name of the sub-entity. example: Lido CSM 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.