> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Buscar itens por valor em uma lista

> Busca itens de uma lista cujo primary value ou search_keys coincidam com um ou mais valores (string ou array), exato ou por substring.

## Visão geral

Busca **itens dentro de uma lista específica** (UUID). Usa **`primary_value`** e **`search_keys`**, com **normalização sem acentos** alinhada às outras buscas.

**`value`** pode ser **string** (uma agulha) ou **array de strings** (até **50**; duplicatas removidas após normalizar). Semântica **OR**: o item aparece **no máximo uma vez** se coincidir com **qualquer** agulha.

* **`exact`** (padrão): igualdade normalizada com o primary ou com alguma chave.
* **`contains`**: subcadeia no primary ou em alguma chave.

Por padrão só itens **`is_active: true`**; use `includeInactive: true` para incluir inativos.

## Endpoint

```
POST https://api.gu1.ai/data-lists/{id}/items/find
```

## Autenticação

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Corpo da solicitação

<ParamField body="value" type="string | string[]" required>
  Uma agulha (`string`, 1–4000) ou até **50** agulhas (`string[]`, cada 1–4000). Strings vazias após `trim` são ignoradas; duplicatas colapsam após normalizar acentos.
</ParamField>

<ParamField body="matchMode" type="string" default="exact">
  `exact` ou `contains`.
</ParamField>

<ParamField body="limit" type="number" default="100">
  Máximo de linhas (1–500). `truncated` indica se há mais resultados que `limit`.
</ParamField>

<ParamField body="includeInactive" type="boolean" default="false">
  Com `true`, inclui itens inativos.
</ParamField>

## Exemplos

**Um valor**

```json theme={null}
{
  "value": "20123456789",
  "matchMode": "exact"
}
```

**Vários valores (OR)**

```json theme={null}
{
  "value": ["20123456789", "30701234567"],
  "matchMode": "exact",
  "limit": 100
}
```

## Resposta

Inclui `data.valuesSearched` (número de agulhas distintas após deduplicar), além de `items`, `total`, `returned`, `truncated`, `matchMode`, `listId` — mesmo formato snake\_case de [Listar itens](/pt/api-reference/data-lists/list-items).

## Ver também

* [Listar itens](/pt/api-reference/data-lists/list-items)
* [Consultar valor por tipo](/pt/api-reference/data-lists/check-value)