Skip to main content

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.

​
Overview

OathNet uses daily quotas to manage API usage. Each plan has a set number of lookups available per day.

​
Quota Reset

Your daily quota resets 24 hours after your first lookup of the day. This is a rolling window, not a fixed time. For example:
  • If your first lookup is at 2:00 PM, your quota resets the next day at 2:00 PM
  • The exact reset time is shown in the response metadata

​
Checking Your Quota

Envelope search responses expose lookup usage in _meta.lookups: 
{
  "success": true,
  "data": { "...": "..." },
  "_meta": {
    "lookups": {
      "used_today": 50,
      "left_today": 450,
      "daily_limit": 500,
      "is_unlimited": false
    }
  }
}
Not every successful endpoint includes quota metadata. Search endpoints do; raw job endpoints and file-stream endpoints may not.

​
Optimizing Quota Usage

​
Use Search Sessions

Search sessions let you perform multiple searches for the same query while only consuming one lookup: 
# Initialize session (counts as 1 lookup)
session = requests.post(
    "https://oathnet.org/api/service/search/init",
    json={"query": "user@example.com"},
    headers={"x-api-key": API_KEY}
).json()

session_id = session["data"]["session"]["id"]

# Additional searches with same session don't consume quota
for page in range(10):
    response = requests.get(
        "https://oathnet.org/api/service/v2/breach/search",
        params={"q": "user@example.com", "search_id": session_id},
        headers={"x-api-key": API_KEY}
    )
See Search Sessions for more details.

​
Failed Requests Don’t Count

Failed requests (4xx/5xx errors) do not count against your quota. You’re only charged for successful lookups.

​
Plan Quotas

Each plan has different quota limits. View current plans and quotas at:

View Pricing

See quota limits for each plan

​
Handling Quota Exhaustion

When your quota is exhausted, you’ll receive a 429 response: 
{
  "success": false,
  "message": "Daily quota exceeded"
}
Options when this happens:
  • Wait for your quota to reset (24 hours from first lookup)
  • Upgrade your plan for more lookups

​
Best Practices

Track _meta.lookups.left_today on envelope search responses to avoid unexpected quota exhaustion:
response = api_call(query)
lookups = response.get("_meta", {}).get("lookups", {})
lookups_left = lookups.get("left_today")

if lookups_left is not None and lookups_left < 100:
    print(f"Warning: Only {lookups_left} lookups remaining")
For repeated searches on the same query, always use search sessions to minimize quota usage.
Cache API responses locally to avoid redundant lookups:
from functools import lru_cache

@lru_cache(maxsize=1000)
def cached_search(query):
    return api_call(query)

​
Questions?

Contact support@oathnet.org if you have questions about quotas or need a custom plan.