> ## 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 Entities > Returns the market share of every curated builder entity over an evaluation window: one row per entity with the proposals its builders won and the value of their accepted bids, next to the totals of the whole network in `network`. The share counts who signed the winning bid. A builder belongs to an entity when its registry entry withdraws to an execution layer address that beaconcha.in curated under the entity's name. Every curated entity has a row, also when its builders won nothing in the window. Self-built proposals, and proposals won by a builder without a curated entity, are totals in `network`, not rows, so every row's `entity` is a value the `builder_entity` selector accepts. A relay, a service that forwards payloads from other builders, can sign bids for their payloads under its own registry entry. An entity of kind `relay` therefore counts the bids the relay signed, not the builders that built those payloads; to name those builders, see [v2/ethereum/builders/fee-recipients](/api-reference/ethereum/builders/fee-recipients). 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 `data` can list few or no entities, most proposals won by an external builder count in `network.unattributed_blocks`, and that is expected. 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. Bid values are stored in Gwei and returned in wei. Results can be sorted by `blocks_won` or `bid_value_total`, descending by default, and are paginated with a default and maximum page size of 10. Combine this endpoint with others for deeper insights: - The record of one entity's builders, with payload and payment outcomes: [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate) with a `builder_entity` selector - The builders of an entity: [v2/ethereum/builders/metadata](/api-reference/ethereum/builders/metadata) - The proposals of one entity, one row each: [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) with `builder_entity` set to the row's `entity` **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/entities 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/entities: post: tags: - Builders summary: 💎 Builder Entities description: > Returns the market share of every curated builder entity over an evaluation window: one row per entity with the proposals its builders won and the value of their accepted bids, next to the totals of the whole network in `network`. The share counts who signed the winning bid. A builder belongs to an entity when its registry entry withdraws to an execution layer address that beaconcha.in curated under the entity's name. Every curated entity has a row, also when its builders won nothing in the window. Self-built proposals, and proposals won by a builder without a curated entity, are totals in `network`, not rows, so every row's `entity` is a value the `builder_entity` selector accepts. A relay, a service that forwards payloads from other builders, can sign bids for their payloads under its own registry entry. An entity of kind `relay` therefore counts the bids the relay signed, not the builders that built those payloads; to name those builders, see [v2/ethereum/builders/fee-recipients](/api-reference/ethereum/builders/fee-recipients). 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 `data` can list few or no entities, most proposals won by an external builder count in `network.unattributed_blocks`, and that is expected. 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. Bid values are stored in Gwei and returned in wei. Results can be sorted by `blocks_won` or `bid_value_total`, descending by default, and are paginated with a default and maximum page size of 10. Combine this endpoint with others for deeper insights: - The record of one entity's builders, with payload and payment outcomes: [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate) with a `builder_entity` selector - The builders of an entity: [v2/ethereum/builders/metadata](/api-reference/ethereum/builders/metadata) - The proposals of one entity, one row each: [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) with `builder_entity` set to the row's `entity` **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. operationId: GetBuilderEntities requestBody: $ref: '#/components/requestBodies/builderEntities' responses: '200': $ref: '#/components/responses/BuilderEntities' '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: builderEntities: x-go-name: BuilderEntitiesRequestBody content: application/json: schema: $ref: '#/components/schemas/BuilderEntitiesRequest' example: chain: hoodi range: evaluation_window: 30d sort_by: blocks_won sort_order: desc responses: BuilderEntities: description: Successful response. content: application/json: schema: allOf: - $ref: '#/components/schemas/BuilderEntities.Container' - $ref: '#/components/schemas/PagingTemplate' description: >- Response containing the market share of the curated builder entities over the evaluation window, next to the network totals. 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: BuilderEntitiesRequest: type: object properties: chain: $ref: '#/components/schemas/Chain' range: $ref: '#/components/schemas/NamedBuilderEvaluationWindow' cursor: $ref: '#/components/schemas/Cursor' page_size: $ref: '#/components/schemas/PageSize' sort_by: $ref: '#/components/schemas/BuilderEntitiesSortField' sort_order: $ref: '#/components/schemas/SortOrder' required: - range BuilderEntities.Container: type: object description: >- Response containing the market share of the curated builder entities over the evaluation window, next to the network totals. properties: data: type: array items: $ref: '#/components/schemas/BuilderEntities.Data' network: $ref: '#/components/schemas/BuilderEntities.Network' range: $ref: '#/components/schemas/ResultRange' required: - data - network - range PagingTemplate: type: object properties: paging: $ref: '#/components/schemas/Paging' 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 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 BuilderEntitiesSortField: type: string enum: - blocks_won - bid_value_total x-enum-varnames: - BuilderEntitiesSortBlocksWon - BuilderEntitiesSortBidValueTotal default: blocks_won example: blocks_won description: > The field to sort builder entities by. Entities with equal values are sorted by name. - `blocks_won`: Sort by the proposals won (default) - `bid_value_total`: Sort by the summed value of the accepted bids SortOrder: type: string enum: - asc - desc default: desc description: | The sort order for the results. - `asc`: Ascending order (lowest first) - `desc`: Descending order (highest first, default) BuilderEntities.Data: type: object description: >- The proposals won by the builders of one curated builder entity over the evaluation window. properties: entity: allOf: - $ref: '#/components/schemas/BuilderEntityName' description: >- Name of the builder entity, a value the `builder_entity` selector accepts. It names who signed the winning bids, which for a relay is not who built the payloads; for that, see [v2/ethereum/builders/fee-recipients](/api-reference/ethereum/builders/fee-recipients). kind: allOf: - $ref: '#/components/schemas/BuilderEntityKind' description: >- Whether the entity is a block builder or a relay. `relay` when any of its addresses is curated as a relay's. builder_execution_addresses: type: array items: $ref: '#/components/schemas/ExecutionLayerAddress' description: >- Execution layer addresses curated under the entity. A builder belongs to the entity when its registry entry withdraws to one of them. One entry per address that beaconcha.in curated under the entity, not one per builder; a builder that registers with one of these addresses adds to `builder_count`, not to this list. builder_count: type: integer description: >- Builder public keys registered with one of `builder_execution_addresses`. blocks_won: type: integer description: >- Canonical proposals in the window whose accepted bid one of the entity's builders signed, including those whose execution payload the chain did not include. block_share: allOf: - $ref: '#/components/schemas/percent' description: >- `blocks_won` as a fraction of `network.blocks`, which includes the self-built payloads. `0` when `network.blocks` is `0`. bid_value_total: allOf: - $ref: '#/components/schemas/wei' description: >- Summed value of the accepted bids won. Stored in Gwei, returned in wei. value_share: allOf: - $ref: '#/components/schemas/percent' description: >- `bid_value_total` as a fraction of `network.bid_value_total`. `0` when `network.bid_value_total` is `0`. payload: $ref: '#/components/schemas/BuilderPerformance.Payload' required: - entity - kind - builder_execution_addresses - builder_count - blocks_won - block_share - bid_value_total - value_share - payload BuilderEntities.Network: type: object description: >- Every canonical proposal of the network over the evaluation window. Self-built and unattributed proposals are totals here, not entity rows, so every row's `entity` stays a value the `builder_entity` selector accepts. properties: blocks: type: integer description: Canonical proposals in the window, self-built ones included. self_built_blocks: type: integer description: Proposals whose proposer built the execution payload itself. unattributed_blocks: type: integer description: >- Proposals won by an external builder that belongs to no curated builder entity, or whose builder is not in beaconcha.in's copy of the registry. 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 most proposals won by an external builder count here. bid_value_total: allOf: - $ref: '#/components/schemas/wei' description: >- Summed value of every accepted bid in the window. Stored in Gwei, returned in wei. external_payload: allOf: - $ref: '#/components/schemas/BuilderPerformance.Payload' description: >- What happened to the execution payloads of the proposals won by external builders, self-built ones excluded, so `full` plus `empty` is `blocks` minus `self_built_blocks`. It is the sum of every row's `payload` and the unattributed proposals' outcomes. The self-built split is `self_built.payload` on [v2/ethereum/builders/network-performance-aggregate](/api-reference/ethereum/builders/network-performance-aggregate). required: - blocks - self_built_blocks - unattributed_blocks - bid_value_total - external_payload 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 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 example: eyJfc2FtcGxlX2N1cnNvciI6MTIzNDU2Nzg5MH0 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 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. BuilderEntityKind: type: string enum: - builder - relay x-enum-varnames: - BuilderEntityKindBuilder - BuilderEntityKindRelay example: builder description: > What a curated builder entity is. - `builder`: a block builder. - `relay`: a relay. A relay can bid under its own builder registry entry for payloads that other builders built, so its bids name the relay, not the builder of the payload. ExecutionLayerAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: A standard Ethereum address (20-byte hex string with 0x prefix). example: '0x388C818CA8B9251b393131C08a736A67ccB19297' percent: type: number format: float minimum: 0 maximum: 1 example: 0.95 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 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.