Holehe Module Results Output Format: Complete Schema and Usage Guide

Holehe returns the results of every module as a standardized Python dictionary containing ten consistent keys—including exists, rateLimit, and emailrecovery—that can be directly serialized to JSON for automated OSINT processing.

Holehe is an open-source intelligence (OSINT) tool that checks whether email addresses are registered on hundreds of websites and social media platforms. When you execute a scan, each module queries a specific service and returns its findings in a predictable, machine-readable structure. Understanding the holehe module results output format is essential for building automated workflows, parsing account existence data, and integrating findings into external security tools.

The Standardized Holehe Output Schema

Every module in the repository—whether checking Twitter, Facebook, or niche services—returns results using an identical dictionary structure. This schema is enforced by the print_result function in holehe/core.py and implemented consistently across all modules located in holehe/modules/.

The dictionary contains the following fields:

• name: Internal module identifier (e.g., "twitter")
• domain: The target domain being checked (e.g., "twitter.com")
• method: The verification technique used ("register", "login", or "other")
• frequent_rate_limit: Boolean indicating whether the service is known for frequent rate limiting
• rateLimit: Boolean set to True when the specific request encountered rate limiting; otherwise False
• exists: Boolean indicating whether the email is associated with an existing account on the service
• emailrecovery: Partially obfuscated recovery email address (e.g., "ex****e@gmail.com") or None
• phoneNumber: Partially obfuscated recovery phone number (e.g., "0*******78") or None
• others: Additional service-specific information such as FullName or custom error messages, or None when not applicable
• error: Optional boolean present only when unexpected exceptions occur; when True, rateLimit is typically False

The JSON-equivalent representation follows this structure:

{
  "name": "example",
  "domain": "example.com",
  "method": "register",
  "frequent_rate_limit": false,
  "rateLimit": false,
  "exists": true,
  "emailrecovery": "ex****e@gmail.com",
  "phoneNumber": "0*******78",
  "others": null
}

Where the Output Format Is Defined

The standardized schema originates in two critical locations within the megadose/holehe codebase.

Core Logic in holehe/core.py

The print_result function in holehe/core.py (lines 22-48) expects and processes the dictionary keys listed above. This function validates that all modules return consistent data structures before formatting results for console output or CSV export.

Module Implementation Example

Individual modules construct these dictionaries using raw HTTP responses. The Twitter module in holehe/modules/social_media/twitter.py (lines 5-37) demonstrates the standard implementation pattern, extracting account existence data and populating each required field before appending the dictionary to the results list.

Working with Holehe Module Results Programmatically

You can capture the raw dictionary output directly in Python without invoking the command-line interface. The following examples demonstrate how to process holehe module results in custom scripts.

Basic Single Module Usage

Import individual modules and capture results by passing a list container:

import trio
import httpx
from holehe.modules.social_media.twitter import twitter

async def check_single_service():
    email = "test@example.com"
    results = []
    
    async with httpx.AsyncClient() as client:
        await twitter(email, client, results)
    
    # results contains the standardized dictionary

    for result in results:
        print(f"Service: {result['name']}, Exists: {result['exists']}")

trio.run(check_single_service)

Full Concurrent Scan with All Modules

To execute all available modules simultaneously and collect comprehensive results:

import trio
import httpx
from holehe.core import import_submodules, get_functions, launch_module

async def run_full_holehe_scan(email):
    modules = import_submodules("holehe.modules")
    websites = get_functions(modules)
    results = []
    
    async with httpx.AsyncClient(timeout=10) as client:
        async with trio.open_nursery() as nursery:
            for website in websites:
                nursery.start_soon(launch_module, website, email, client, results)
    
    return sorted(results, key=lambda x: x["name"])

# Execute scan

email_results = trio.run(run_full_holehe_scan, "test@example.com")
for entry in email_results:
    status = "Account found" if entry["exists"] else "No account"
    print(f"{entry['domain']}: {status}")

Exporting and Serializing Results

The standardized dictionary format enables seamless export to JSON and CSV without data transformation.

JSON Serialization

Since holehe module results are native Python dictionaries, they serialize directly to JSON:

import json

# Assuming results is the list from previous examples

json_output = json.dumps(results, indent=2)
print(json_output)

CSV Export Functionality

The framework includes built-in CSV export via the export_csv function in holehe/core.py:

import datetime
from holehe.core import export_csv

# Export results to timestamped CSV file

export_csv(
    results, 
    args=type("Args", (), {"csvoutput": True}), 
    email="test@example.com"
)

# Creates: holehe_1700000000_test@example.com_results.csv

Summary

• Holehe modules return standardized Python dictionaries with ten specific keys including exists, rateLimit, and emailrecovery.
• The output format is strictly defined in holehe/core.py (lines 22-48) and implemented in modules like holehe/modules/social_media/twitter.py (lines 5-37).
• Results are JSON-serializable by default, enabling direct integration with external APIs and security platforms.
• The print_result and export_csv utilities in the core library handle console formatting and file export without requiring manual data manipulation.
• Boolean flags indicate account existence (exists) and rate-limiting status (rateLimit), while sensitive recovery data uses partial obfuscation.

Frequently Asked Questions

What data types does Holehe return for module results?

Holehe returns Python dictionaries with string values for identifiers (name, domain, method) and boolean values for status flags (exists, rateLimit, frequent_rate_limit). Recovery fields (emailrecovery, phoneNumber) return obfuscated strings or None. This structure serializes directly to JSON arrays without type conversion.

How do I check if an email was found on a specific service using Holehe output?

Inspect the exists boolean key in the result dictionary. When exists is True, the email is registered on that service. When False, no account was found. If rateLimit is True, the exists value may be unreliable due to request blocking by the target service.

What does the others field contain in Holehe module results?

The others field stores service-specific metadata that does not fit standard categories, such as full names, profile URLs, or custom error messages. It returns None when no additional data is available. Unlike the consistent structure of emailrecovery or phoneNumber, the content of others varies by module depending on what information each service exposes.

Can I modify the output format of Holehe modules?

While the core schema is standardized in holehe/core.py, you can extend individual modules in holehe/modules/ to capture additional data fields. However, removing or renaming the required keys (name, domain, method, exists, etc.) will break compatibility with the print_result function and CSV export utilities in the core library.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}