Bulk Search Guide

Overview

Bulk search is for batched investigations where one search shape needs to run against many terms. Instead of sending hundreds of separate search requests, you create one job with a shared query_config and a list of terms. Use bulk search when:

you have many domains, emails, usernames, or identifiers to check
each term should reuse the same service, fields, filters, and output format
you want an asynchronous job with status polling and a downloadable result

For one-off searches, use the normal breach, stealer, or victims search guides.

How It Works

create one job with the shared search shape and all target terms
poll the job until it finishes
download the generated output file
list recent jobs when you need history or recovery after a client restart

Bulk search responses are job snapshots. Create responses use the standard success/data envelope; list and status responses are raw JSON snapshots.

Query Config

query_config is the reusable part of the search. It can contain the same flat filters and structured filter grammar used by normal V2 search.

{
  "service": "breach",
  "format": "jsonl",
  "terms": ["example.com", "example.org"],
  "query_config": {
    "filter": {
      "field": "email_domain",
      "operator": "eq",
      "value": "example.com"
    },
    "date_field": "indexed_at",
    "from": "2026-03-01T00:00:00Z",
    "to": "2026-03-31T23:59:59Z"
  },
  "limit": 1000,
  "fields": ["email", "username", "password", "dbname"]
}

Supported service values are stealer, docs, victims, and breach. Supported format values are csv, json, jsonl, txt, and html.

Polling

Bulk jobs may include next_poll_after_ms. Prefer that value when present, and fall back to a conservative interval when it is missing.

import time
import requests

headers = {"x-api-key": "YOUR_API_KEY"}
job_id = "5a947390178c534af14dd075"

while True:
    snapshot = requests.get(
        f"https://oathnet.org/api/service/v2/bulk-search/{job_id}",
        headers=headers,
    ).json()

    if snapshot["status"] in {"completed", "failed", "cancelled"}:
        break

    time.sleep(snapshot.get("next_poll_after_ms", 2000) / 1000)

Downloads

The download endpoint returns a file or text stream, not JSON. Save the response body directly.

curl -X GET "https://oathnet.org/api/service/v2/bulk-search/5a947390178c534af14dd075/download" \
  -H "x-api-key: YOUR_API_KEY" \
  -o bulk-search.jsonl

Exact Request Details

Use the OpenAPI reference for the complete schema, enum list, response fields, and playground requests for each bulk-search endpoint.

Getting Started

Search Guides

OSINT And Utility Guides

Integration Guides

Resources

Overview

How It Works

Query Config

Polling

Downloads

Exact Request Details

​Overview

​How It Works

​Query Config

​Polling

​Downloads

​Exact Request Details

Overview

How It Works

Query Config

Polling

Downloads

Exact Request Details