Skip to main content

​
What are Search Sessions?

Search sessions are a way to maximize the value of each lookup in your plan. When you initialize a search session, you can perform multiple searches across different services (breach, stealer, OSINT) for the same query while only consuming a single lookup from your daily quota.

View Plan Quotas

Check how many lookups are included in each plan

​
Why Use Search Sessions?

Without a search session: Each API call deducts 1 lookup from your daily quota.With a search session: Multiple calls for the same query consume only 1 lookup (within the session quota).

​
Example Comparison

ScenarioWithout SessionWith Session
Search breach for [email protected]1 lookup1 lookup
Search stealer for [email protected]1 lookup0 lookups (same session)
Discord lookup1 lookup0 lookups (same session)
Total3 lookups1 lookup
Each plan has a session quota that determines how many searches you can perform within a single session. See pricing for details.

​
Creating a Session

Initialize a session before making related queries: 
curl -X POST "https://oathnet.org/api/service/search/init" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "[email protected]"
  }'

​
Using a Session

Pass the session ID using the search_id parameter to subsequent API calls: 
session_id = "sess_1234567890abcdef"

# All these searches use the same session = 1 lookup total
breach_results = requests.get(
    "https://oathnet.org/api/service/search-breach",
    params={"q": "[email protected]", "search_id": session_id},
    headers={"x-api-key": API_KEY}
).json()

stealer_results = requests.get(
    "https://oathnet.org/api/service/v2/stealer/search",
    params={"q": "[email protected]", "search_id": session_id},
    headers={"x-api-key": API_KEY}
).json()

​
Smart Query Detection

The q parameter uses smart query detection to automatically determine the type of your search:
Highlighted Feature: You don’t need to specify the query type - OathNet automatically detects it based on the format of your query.
Query FormatDetected TypeExample
Contains @ and domainemail[email protected]
Valid domain formatdomainexample.com
IPv4 or IPv6 addressip192.168.1.1
14-19 digit numberdiscord_id123456789012345678
17-digit numbersteam_id76561198012345678
Other alphanumericusernamejohn_doe_123

​
Session Duration

  • Sessions are valid for 60 minutes from creation
  • After expiration, you need to create a new session
  • Each new session for a different query consumes a lookup
You can make API calls without initializing a session first: 
# Works, but each call deducts 1 lookup
response = requests.get(
    "https://oathnet.org/api/service/search-breach",
    params={"q": "[email protected]"},
    headers={"x-api-key": API_KEY}
)
This approach is not recommended as you’ll consume more lookups from your quota. Always use search sessions for better value.

​
Quota Reset

Your daily lookup quota resets 24 hours after your first lookup of the day.

​
Best Practices

For any investigation, always start with a session:
# Step 1: Initialize session
session = init_session("[email protected]")

# Step 2: Use session for all related searches
search_breach(session["id"])
search_stealer(session["id"])
lookup_discord(session["id"])
Create a new session for each distinct query you’re investigating:
# Investigation 1
session1 = init_session("[email protected]")

# Investigation 2 (different query = new session)
session2 = init_session("[email protected]")
Sessions last 60 minutes - reuse them for follow-up searches on the same query:
session = init_session("[email protected]")

# Initial search
breach_results = search_breach(session["id"])

# Later (within 60 min) - still uses same session
more_results = search_stealer(session["id"])

​
Next Steps

Pagination

Handle large result sets

Error Handling

Handle errors gracefully