> ## 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 Metadata > Returns the curated labels of a set of builders: one row per tenure in the beacon chain's builder registry, with its builder index, public key, execution layer address and epochs, and the builder entity, sub-entity and kind that beaconcha.in curated for that address. A label is null when the address has none. The labels name who signed a bid, the builder in the registry. A relay can bid under its own registry entry for payloads that other builders built; its rows then name the relay, with `kind` `relay`. To label proposals, join the rows of [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) or [v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots) on `execution_payload.builder_pubkey`, and take the tenure whose `deposit_epoch` is at or before the proposal's epoch and whose `superseded_epoch` is after it or null. 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 labels are null. Results are paginated with a default and maximum page size of 10, newest `deposit_epoch` first. **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/metadata 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/metadata: post: tags: - Builders summary: 💎 Builder Metadata description: > Returns the curated labels of a set of builders: one row per tenure in the beacon chain's builder registry, with its builder index, public key, execution layer address and epochs, and the builder entity, sub-entity and kind that beaconcha.in curated for that address. A label is null when the address has none. The labels name who signed a bid, the builder in the registry. A relay can bid under its own registry entry for payloads that other builders built; its rows then name the relay, with `kind` `relay`. To label proposals, join the rows of [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) or [v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots) on `execution_payload.builder_pubkey`, and take the tenure whose `deposit_epoch` is at or before the proposal's epoch and whose `superseded_epoch` is after it or null. 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 labels are null. Results are paginated with a default and maximum page size of 10, newest `deposit_epoch` first. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. operationId: GetBuilderMetadata requestBody: $ref: '#/components/requestBodies/builderMetadata' responses: '200': $ref: '#/components/responses/BuilderMetadata' '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: builderMetadata: x-go-name: BuilderMetadataRequestBody content: application/json: schema: $ref: '#/components/schemas/BuilderMetadataRequest' example: chain: hoodi builder: builder_index: 1889 responses: BuilderMetadata: description: Successful response. content: application/json: schema: allOf: - $ref: '#/components/schemas/BuilderMetadata.ContainerList' - $ref: '#/components/schemas/PagingTemplate' description: >- Response containing the selected builder tenures with the curated labels of their execution layer addresses. 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: BuilderMetadataRequest: type: object properties: chain: $ref: '#/components/schemas/Chain' builder: $ref: '#/components/schemas/buildersSelector' cursor: $ref: '#/components/schemas/Cursor' page_size: $ref: '#/components/schemas/PageSize' required: - builder BuilderMetadata.ContainerList: type: object properties: data: type: array items: $ref: '#/components/schemas/BuilderMetadata.Data' required: - data 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. 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' 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 BuilderMetadata.Data: type: object description: >- One tenure in the beacon chain's builder registry with the curated labels of its execution layer address. properties: builder_index: allOf: - $ref: '#/components/schemas/BuilderIndex' description: Index the builder held during this tenure. builder_pubkey: $ref: '#/components/schemas/BuilderPublicKey' builder_execution_address: allOf: - $ref: '#/components/schemas/ExecutionLayerAddress' description: >- Execution layer address that the registry entry names for the builder's withdrawals. The labels below are curated for this address. deposit_epoch: allOf: - $ref: '#/components/schemas/Epoch' description: >- The registry's deposit epoch of the builder; see [v2/ethereum/builders](/api-reference/ethereum/builders/overview). A proposal belongs to this tenure when its accepted bid names `builder_index` and its epoch is at least `deposit_epoch` and below `superseded_epoch`. superseded_epoch: nullable: true allOf: - $ref: '#/components/schemas/Epoch' description: >- Epoch from which `builder_index` belongs to the next builder registered at it. Null while this builder still holds the index. entity: nullable: true allOf: - $ref: '#/components/schemas/BuilderEntityName' description: >- Builder entity that beaconcha.in curated for `builder_execution_address`, a value the `builder_entity` selector accepts. It names who signed the bids of this tenure, which for a relay is not who built the payloads; for that, see [v2/ethereum/builders/fee-recipients](/api-reference/ethereum/builders/fee-recipients). Null when the address has no curated name. 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 entities are null. sub_entity: nullable: true allOf: - $ref: '#/components/schemas/SubEntityName' description: >- Sub-entity of `entity` curated for `builder_execution_address`. Null when the address has no curated sub-entity. kind: nullable: true allOf: - $ref: '#/components/schemas/BuilderEntityKind' description: >- Whether `entity` is a block builder or a relay. Null when `entity` is null. required: - builder_index - builder_pubkey - builder_execution_address - deposit_epoch - superseded_epoch - entity - sub_entity - kind 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 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 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. 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. ExecutionLayerAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: A standard Ethereum address (20-byte hex string with 0x prefix). example: '0x388C818CA8B9251b393131C08a736A67ccB19297' Epoch: type: integer minimum: 0 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 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. 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.