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

# Breach Search Guide

> Understand breach search workflows, filters, autocomplete, and AI-assisted discovery

## Overview

Breach search is the best starting point when you want account, identity, and
source-dataset rows from indexed breach collections. Use it when the question is
"where does this email, username, phone, domain, or identifier appear across
breach sources?"

Think of the breach workflow in four parts:

* search for rows with a broad query or exact filters
* narrow the search to known breach sources, fields, dates, or structured logic
* use autocomplete before large searches to discover valid db names and fields
* use AI filters when a user describes the target in natural language

## Basic Search

Successful V2 breach searches use the standard envelope: `success`, `message`, `data`, and `_meta`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://oathnet.org/api/service/v2/breach/search" \
    -H "x-api-key: YOUR_API_KEY" \
    --data-urlencode "q=user@example.com" \
    --data-urlencode "dbname[]=linkedin_2012"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://oathnet.org/api/service/v2/breach/search",
      params={
          "q": "user@example.com",
          "dbname[]": ["linkedin_2012"],
      },
      headers={"x-api-key": "YOUR_API_KEY"},
  )

  payload = response.json()
  print(payload["data"]["meta"]["total"])
  print(payload.get("_meta", {}).get("lookups", {}).get("left_today"))
  ```
</CodeGroup>

```json Response Example theme={null}
{
  "success": true,
  "message": "Breach search completed",
  "data": {
    "items": [
      {
        "email": "user@example.com",
        "email_domain": "example.com",
        "username": "user123",
        "password": "hunter2",
        "country": "US",
        "dbname": "linkedin_2012"
      }
    ],
    "meta": {
      "count": 1,
      "total": 1,
      "took_ms": 8,
      "has_more": false,
      "total_pages": 1
    },
    "next_cursor": null
  },
  "_meta": {
    "lookups": {
      "left_today": 9998
    }
  }
}
```

## Filters And Pagination

The current search endpoint supports:

* `q` for broad auto-detected queries
* flat filters such as `email[]`, `phone[]`, `country[]`, `dbname[]`, and `password_hash[]`
* `logic=and|or`
* `wildcard=true`
* `cursor` for pagination
* `filter` and `filter_id` for structured filtering

Use `data.next_cursor` when `data.meta.has_more` is `true`.

See [Structured Filters](/guides/structured-filters) for operator semantics such as `gte`, `ends_with`, `wildcard`, `exists`, age/date-of-birth behavior, and `filter_id` merge rules.

## Natural Language Filters

For customer workflows, the AI filter flow is often easier than building JSON filters by hand.

```python theme={null}
import requests

filter_response = requests.post(
    "https://oathnet.org/api/service/v2/ai/filter",
    json={
        "index": "breach",
        "query": "US banking customers with gmail addresses and linkedin data"
    },
    headers={"x-api-key": "YOUR_API_KEY"},
)

filter_id = filter_response.json()["filter_id"]

search_response = requests.get(
    "https://oathnet.org/api/service/v2/breach/search",
    params={"filter_id": filter_id},
    headers={"x-api-key": "YOUR_API_KEY"},
)
```

## Discovery Helpers

Use the autocomplete endpoints before large searches when you need to discover valid db names, fields, or common field values.

<CardGroup cols={2}>
  <Card title="Structured Filters" icon="filter" href="/guides/structured-filters">
    Build nested logic, ranges, existence checks, and reusable filters
  </Card>

  <Card title="Discovery Utilities" icon="sparkles" href="/guides/utilities">
    Learn how autocomplete helps choose fields and db names before searching
  </Card>

  <Card title="Pagination" icon="list" href="/guides/pagination">
    Page through large result sets without losing cursor state
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Use OpenAPI for exact paths, parameters, schemas, and playground requests
  </Card>
</CardGroup>