Holehe Output Dictionary Structure: Complete Field Reference

The Holehe output dictionary contains ten standardized keys—including name, domain, exists, and rateLimit—that modules populate to report email registration status on target sites, with failed checks omitting the method and frequent_rate_limit metadata.

The megadose/holehe framework orchestrates OSINT investigations by executing dozens of site-specific modules in parallel. Each module appends a standardized Python dictionary to a central results list, enabling consistent parsing across disparate websites. Understanding this Holehe output dictionary structure is essential for building custom exporters, automating response handling, or extending the tool with new reconnaissance modules.

Anatomy of the Holehe Output Dictionary

Every entry in the Holehe results list follows a strict schema defined in holehe/core.py. The print_result function and export_csv routine rely on these specific keys to generate colored terminal output and columnar data files.

Core Identity Fields

• name (str): The module identifier, typically matching the target service (e.g., twitter, github, instagram).
• domain (str): The canonical hostname of the website being checked (e.g., twitter.com).

Status and Boolean Flags

• exists (bool): Indicates whether the email address is registered on the target platform.
• rateLimit (bool): Set to True when the remote server returns a rate-limit response (HTTP 429 or equivalent).
• error (bool): Signals that the module raised an exception or failed to complete the network request.
• frequent_rate_limit (bool): Metadata flag indicating whether the site is known for aggressive rate limiting; present only in successful module executions.

Recovered Intelligence Fields

• emailrecovery (str | None): Contains any password-reset email hint or alias leaked by the target service (e.g., j***@gmail.com).
• phoneNumber (str | None): Stores partially masked phone numbers returned by the site during account recovery flows.
• others (dict | None): A flexible container for miscellaneous data such as full names, account creation dates, or geographic locations returned by the module.

Request Metadata (Successful Checks Only)

• method (str): The HTTP verb used for the request (GET, POST, etc.).

Entries produced by the error handler in launch_module omit method and frequent_rate_limit because the request never completed successfully.

How holehe/core.py Processes Results

In holehe/core.py, the launch_module function wraps each module execution in a try-except block. When a module succeeds, it returns a dictionary containing all ten fields. If an exception occurs, the except block appends a fallback dictionary containing only the mandatory keys (name, domain, rateLimit, error, exists, emailrecovery, phoneNumber, others) with error set to True and remaining values defaulted to False or None.

The print_result function iterates over the aggregated list and color-codes output based on the exists, rateLimit, and error flags. Similarly, the export_csv routine uses these keys as column headers when writing results to disk.

Practical Code Examples

Successful reconnaissance against a registered account returns a fully populated dictionary:

# Result from holehe/modules/social_media/twitter.py

{
    "name": "twitter",
    "domain": "twitter.com",
    "method": "GET",
    "frequent_rate_limit": False,
    "rateLimit": False,
    "error": False,
    "exists": True,
    "emailrecovery": "j***@example.com",
    "phoneNumber": None,
    "others": {"FullName": "John Doe", "Location": "San Francisco"}
}

When a module crashes or times out, the error handler generates a minimal entry:

# Error fallback generated by launch_module in holehe/core.py

{
    "name": "instagram",
    "domain": "instagram.com",
    "rateLimit": False,
    "error": True,
    "exists": False,
    "emailrecovery": None,
    "phoneNumber": None,
    "others": None
}

Access the complete results list (typically named out) after execution:

import json
from holehe.core import launch_module, print_result

# After running modules...

results = out  # The shared list populated by all modules

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

Summary

• The Holehe output dictionary uses ten standardized keys to ensure consistent OSINT reporting across all modules.
• Mandatory fields include name, domain, exists, error, rateLimit, emailrecovery, phoneNumber, and others.
• Conditional fields method and frequent_rate_limit appear only when a module executes without raising an exception.
• Core logic in holehe/core.py handles both successful results and error fallbacks, ensuring the results list remains schema-compliant even when targets are unreachable.

Frequently Asked Questions

What keys are guaranteed in every Holehe result dictionary?

Every dictionary returned by megadose/holehe contains eight mandatory keys: name, domain, exists, error, rateLimit, emailrecovery, phoneNumber, and others. The method and frequent_rate_limit keys are omitted when a module fails or raises an exception.

Why do some Holehe results lack the method field?

The method field is populated only when a module completes its HTTP request successfully. If the module crashes, times out, or encounters a network error, the error handler in holehe/core.py appends a fallback dictionary that excludes this key because no valid HTTP transaction occurred.

How does Holehe represent rate limiting in the output structure?

Holehe uses the boolean rateLimit key to indicate when a server returns an HTTP 429 status or similar throttling response. Additionally, the frequent_rate_limit boolean flag provides metadata about whether the target site is historically prone to aggressive rate limiting, helping analysts differentiate between temporary blocks and persistent anti-automation measures.

What data types can appear in the others field?

The others field accepts either None or a Python dictionary containing site-specific metadata. Common values include full names, account creation timestamps, profile biographies, or geographic locations, depending on what information the target site leaks during the email verification process.

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