# IRPCValueLists.GetLookupItems

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/

Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`

Gets the selectable items of one or more value lists or object types in one call, for example
to fill lookup controls.

- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/GetLookupItems`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-lookup-items`
- **Request:** [`GetLookupItemsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md#request)
- **Response:** [`GetLookupItemsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session. No special vault rights are needed; items the user is not allowed
  to see are left out.
- One [LookupItemRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemRequest/index.md) per list. The response has one
  [LookupItemResponse](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemResponse/index.md) per request, in request order;
  identical requests are run once and their result copied.
- **Deleted items are left out** unless a request has the condition Deleted (5) equal to true,
  in which case only deleted items are returned. This differs from
  [SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md).
- Set `LookupItemRequest.property_def` to the lookup property being edited to apply that
  property's value filter (`PropertyDef.value_list_item_filter`); use -1 for no filter.
- `results_limit` unset or 0 returns all matching items. When a list has more items than the
  limit, `has_more_results` is true; narrow the search with a name condition instead of paging
  (there is no offset).
- In hierarchical lists, the parents of matching items are returned too, so a response can
  contain more items than `results_limit`.
- The order of the items is not specified; sort on the client.
- If any request names an unknown list, the whole call fails with "Not found.".
- For external lists, `external_data_source_refresh` can refresh the list from its external
  database before the read. Not cacheable: item lists change without a metadata structure version change.
- Related: [GetValueListItemProposals](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md)
  for the user's recently used values.

<a id="request"></a>

## Request: GetLookupItemsRequest

Request for getting lookup items of multiple object types or value lists (lookup types).

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `requests[]` | repeated [`LookupItemRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemRequest/index.md) | One request per value list or object type. See [LookupItemRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemRequest/index.md). |
| `requests[].external_data_source_refresh` | [`ExtDBRefreshType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtDBRefreshType/index.md) | For a list connected to an external database: whether to refresh it from the database before the read. `EXT_DBREFRESH_TYPE_NONE` reads the items the vault already has. Values: `EXT_DBREFRESH_TYPE_NONE` (0), `EXT_DBREFRESH_TYPE_QUICK` (1), `EXT_DBREFRESH_TYPE_FULL` (2). |
| `requests[].value_list_id` | `int32` | The ID of the value list or object type whose items are wanted. |
| `requests[].property_def` | `int32` | The ID of the lookup property being edited, to apply its value filter (`PropertyDef.value_list_item_filter`), or -1 for no filter. Set -1 explicitly: the default 0 is a real property definition ID (Name or title). |
| `requests[].search_conditions[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | Item conditions, combined with AND, on the item pseudo properties 1-8 (for example 2 = name); see the [IRPCValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) overview. Deleted items are left out unless the condition Deleted (5) equal to true is given. |
| `requests[].search_conditions[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `requests[].search_conditions[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `requests[].search_conditions[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `requests[].results_limit` | optional `uint32` | The maximum number of items to return. Unset or 0 returns all. |
| `resolve_current_user_placeholders` | `bool` | True to replace the "current user" entry in each item's automatic permissions with the caller's own user ID. |
| `include_permissions` | `bool` | True to fill `acl` and `current_user_permissions` of each returned item. Leave false if you need only IDs and names. |
| `timeout_in_seconds` | `uint32` | 0 for no timeout. Otherwise the server checks the elapsed time between the steps of the call and fails it with a timeout error once the limit has passed. |

<a id="response"></a>

## Response: GetLookupItemsResponse

Search multiple object type items response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `lookup_item_results[]` | repeated [`LookupItemResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LookupItemResponse/index.md) | One result per request, in the order of `requests`. |
| `lookup_item_results[].value_list_id` | `int32` | The `value_list_id` of the request. |
| `lookup_item_results[].items[]` | repeated [`ValueListItemData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemData/index.md) | The matching items, with permissions if the request had `include_permissions`. In hierarchical lists the parents of matching items are included. |
| `lookup_item_results[].items[].item` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The item. See [ValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md). |
| `lookup_item_results[].items[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The access control list of the item. Set only when the request had `include_permissions`. |
| `lookup_item_results[].items[].current_user_permissions` | [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | What the caller may do with the item. Set only when the request had `include_permissions`. |
| `lookup_item_results[].has_more_results` | `bool` | True if more items matched than `results_limit` allowed. |

<a id="related"></a>

## Related methods

- [SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md): Searches the items of one value list or object type by item ID, name, owner, parent or deleted state.
- [GetValueListItemProposals](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md): Gets the values that the calling user has most recently used for a lookup property.