--- title: "Search documents" method: GET path: "/api/dataentities/{dataEntityName}/search" tags: ["Search"] --- # Search documents `GET /api/dataentities/{dataEntityName}/search` Retrieves Master Data v2 documents' information, while choosing which fields will be returned and filtering documents by specific fields. > The response header `REST-Content-Range` indicates the total amount of results for that specific search. For example, it may return `resources 0-100/136108`, which indicates it has returned the first 100 results out of a total of 136108. Below you can see some query examples and learn more about each query parameter. Learn more about [Pagination in the Master Data API](https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api). >⚠️ Avoid sending too many requests with wildcards (`*`) in the search parameters or that use the `keyword` parameter. This may lead to this endpoint being temporarily blocked for your account. If this happens you will receive an error with status code `503`. ## Query examples | **Query Type** | **Example** | |-|-| | **Simple filter** | `/dataentities/Newsletter/search?email=my@email.com` | | **Complex filter** | `/dataentities/Newsletter/search?_where=(firstName=Jon OR lastName=Smith) OR (createdIn between 2001-01-01 AND 2016-01-01)` | | **Date range** | `/dataentities/Newsletter/search?_where=createdIn between 2001-01-01 AND 2016-01-01` | | **Range numeric fields** | `/dataentities/Newsletter/search?_where=age between 18 AND 25` | | **Partial filter** | `/dataentities/Newsletter/search?firstName=*Maria*` | | **Filter for null values** | `/dataentities/Newsletter/search?_where=firstName is null` | | **Filter for non-null values** | `/dataentities/Newsletter/search?_where=firstName is not null` | | **Filter for difference** | `/dataentities/Newsletter/search?_where=firstName<>maria` | | **Filter greater than** | `/dataentities/Newsletter/search?_where=number>5` | | **Filter less than** | `/dataentities/Newsletter/search?_where=date<2001-01-01` | ## Permissions Any user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint: | **Product** | **Category** | **Resource** | | --------------- | ----------------- | ----------------- | | Dynamic Storage | Dynamic storage generic resources | **Read only documents** | | Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** | | Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** | | Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** | There are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication). >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations. ## Path parameters - `dataEntityName` string, required ## Query parameters - `_fields` string - `_where` string - `_schema` string - `_sort` string ## Headers - `Content-Type` string, required - `Accept` string, required - `REST-Range` string, required ## Response `200` OK - UsingFieldsAll[] — List of documents that correspond to the result of the search. - `id` string, required — ID of the document. - `accountId` string, required — ID of the VTEX account. - `accountName` string, required — Name of the VTEX account. - `dataEntityId` string, required — Data entity name. ## Other responses - `400` — Bad Request - `403` — Forbidden - `503` — Service Unavailable Wildcard queries temporarily blocked due to excessive usage. Consider adjusting your code to remove them or reduce the rate of search requests with wildcards (*). This temporary block may also be due to excessive use of requests with the parameter `keyword`. ## Changes - **2024-04-04** `eeea1ecf1a05` — 1 warning - deleted the `query` request parameter `_keyword` - **2023-10-19** `5bf3265c027c` — 2 breaking - for the `query` request parameter `_fields`, default value `email,firstName,document` was removed - for the `query` request parameter `_sort`, default value `firstName ASC` was removed - **2023-10-19** `21be1e438b39` — 1 info - added the media type `application/json` for the response with the status `200` - **2023-10-19** `d9626a7ffe42` — 1 breaking, 2 info - removed the media type `application/json` for the response with the status `503` - added the non-success response with the status `400` - added the non-success response with the status `403` [Change history](https://skmtc.dev/vtex/apis/master-data-api-v2/changes/api/dataentities/:dataEntityName/search/get.md) --- [API](https://skmtc.dev/vtex/apis/master-data-api-v2.md) · [All operations](https://skmtc.dev/vtex/apis/master-data-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vtex/master-data-api-v2/revisions/6d3f8010fa54/schema)