> ## 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 ítems por valor en una lista

> Busca ítems de una lista cuyo primary value o search_keys coincidan con uno o más valores (string o array), exacto o por contención.

## Resumen

Busca **ítems dentro de una lista concreta** (UUID). La comparación usa **`primary_value`** y cada **`search_keys`**, con la misma **normalización sin acentos** que el resto de búsquedas.

Podés enviar **`value` como string** (una aguja) o **como array de strings** (hasta **50** entradas; se eliminan duplicados tras normalizar). La semántica es **OR**: cualquier ítem que coincida con **cualquiera** de las agujas aparece **como máximo una vez** en `items`.

* **`exact`** (por defecto): igualdad normalizada con el primary o con alguna clave.
* **`contains`**: subcadena en el primary o en alguna clave (`LIKE` con `%`/`_` escapados en la aguja).

Por defecto solo ítems **`is_active: true`**; con `includeInactive: true` se incluyen inactivos.

## Endpoint

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

## Autenticación

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

## Cuerpo de la solicitud

<ParamField body="value" type="string | string[]" required>
  Una aguja (`string`, 1–4000 caracteres) o hasta **50** agujas (`string[]`, cada una 1–4000). Se ignoran strings vacíos tras `trim`; los duplicados colapsan tras normalizar acentos. Tiene que quedar al menos una aguja no vacía.
</ParamField>

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

<ParamField body="limit" type="number" default="100">
  Máximo de filas devueltas (1–500). Si hay más coincidencias, `truncated` es `true` y `total` es el conteo total.
</ParamField>

<ParamField body="includeInactive" type="boolean" default="false">
  Con `true` incluye ítems inactivos.
</ParamField>

## Ejemplos

**Un valor**

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

**Varios valores (OR)**

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

## Respuesta

Incluye `data.valuesSearched`: cantidad de agujas **distintas** usadas tras deduplicar, además de `listId`, `matchMode`, `items`, `total`, `returned`, `truncated` (mismo formato snake\_case que [Listar ítems](/es/api-reference/data-lists/list-items)).

## Códigos HTTP

* **`404`**: lista inexistente o sin acceso para la organización.
* **`403`**: lista global solo marketplace no expuesta por esta API.

## Ver también

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