> ## 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.

# Find items by value in a list

> POST /data-lists/{id}/items/find — return items in a list whose primary value or search keys match one or more needles (string or array, exact or contains).

## Overview

Looks up **items inside a specific list** (by list UUID). Matching runs against the item’s **`primary_value`** and every entry in **`search_keys`**, using the same accent-insensitive normalization as list search elsewhere.

You can pass **`value` as a string** (one needle) or **as an array of strings** (up to **50** entries; duplicates are removed after normalization). Semantics are **OR**: any item that matches **any** needle is returned **at most once** in `items`.

* **`exact`** (default): normalized needle equals normalized primary **or** equals any search key.
* **`contains`**: normalized needle is a **substring** of primary or of any search key (SQL `LIKE` with wildcards escaped in the needle).

By default only **`is_active: true`** items are returned; set `includeInactive: true` to include inactive rows.

## Endpoint

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

## Authentication

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

## Request Body

<ParamField body="value" type="string | string[]" required>
  One needle (`string`, 1–4000 characters) or up to **50** needles (`string[]`, each 1–4000 characters). Empty strings are ignored; duplicates collapse after trim + accent normalization. At least one non-empty needle is required.
</ParamField>

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

<ParamField body="limit" type="number" default="100">
  Max rows to return (1–500). If more rows match, `truncated` is `true` and `total` is the full count.
</ParamField>

<ParamField body="includeInactive" type="boolean" default="false">
  When `true`, inactive items are included in the search.
</ParamField>

## Examples

**Single value**

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

**Several values (OR)**

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

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "listId": "…",
    "matchMode": "exact",
    "valuesSearched": 3,
    "items": [],
    "total": 0,
    "returned": 0,
    "truncated": false
  }
}
```

`valuesSearched` is the number of **distinct** normalized needles used (after deduplication).

Each item uses the same snake\_case shape as `GET /data-lists/{id}/items` (`id`, `primary_value`, `search_keys`, `item_data`, etc.).

## Status codes

* **`404`**: list not found or not accessible for this organization.
* **`403`**: marketplace-only global list not exposed via this API.

## See Also

* [List items](/en/api-reference/data-lists/list-items) (paginated browse / broad `search` query)
* [Check value by type](/en/api-reference/data-lists/check-value) (membership across all lists of a **type**, not a single list id)