---
title: "Get entities by role requirement lookup"
method: POST
path: "/extensions/entities-by-role-requirement/lookup"
tags: ["Extensions"]
---

# Get entities by role requirement lookup

`POST /extensions/entities-by-role-requirement/lookup`

This endpoint is intended to query for entities that have ever used a given requirement (resource or non-fungible global ID) in their access rules (blueprint authentication templates, owner roles, or role assignments).
This endpoint allows querying by multiple requirements. A maximum of `50` requirements can be queried. A maximum of 20 entities per requirement will be returned.
To retrieve subsequent pages, use the returned cursor and call the `/extensions/entities-by-role-requirement/page` endpoint.

Behaviour:
- Entities are returned in ascending order by the state version in which the requirement was first observed on the ledger.
- It may include entities that no longer use the requirement as part of an access rule.
- If no entities are found, an empty list will be returned.

## Request body

- EntitiesByRoleRequirementLookupRequest
  - `requirements` EntitiesByRoleRequirementRequestRequirement[], required — limited to max 50 items.
    - `resource_address` string, required — Bech32m-encoded human readable version of the address.
    - `non_fungible_id` string — String-encoded non-fungible ID.

## Response `200`

List of entities, per requested requirement, that have ever used the queried requirements in their access rules.

- EntitiesByRoleRequirementLookupResponse
  - `items` EntitiesByRoleRequirementLookupCollection[], required
    - `total_count` integer, nullable — Total number of items in underlying collection, fragment of which is available in `items` collection.
    - `next_cursor` string, nullable — If specified, contains a cursor to query next page of the `items` collection.
    - `requirement` EntitiesByRoleRequirementRequestRequirement, required
      - `resource_address` string, required — Bech32m-encoded human readable version of the address.
      - `non_fungible_id` string — String-encoded non-fungible ID.
    - `entities` EntitiesByRoleRequirementItem[], required
      - `entity_address` string, required — Bech32m-encoded human readable version of the address.
      - `first_seen_state_version` integer, required

## Other responses

- `4XX` — Client-originated request error

---

[API](https://skmtc.net/radixdlt/apis/radix-gateway-api-babylon.md) · [All operations](https://skmtc.net/radixdlt/apis/radix-gateway-api-babylon/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/radixdlt/radix-gateway-api-babylon/revisions/153aecf74342/schema)