Standardized Output Format for Holehe Module Results: Complete Schema Guide

Holehe modules return a unified dictionary containing module, email, username, url, exist, and optional error fields, which the core runner aggregates into a list for consistent programmatic processing.

The megadose/holehe repository provides an open-source email OSINT framework for checking account existence across hundreds of services. Understanding the standardized output format is essential for developers integrating Holehe into automated workflows or parsing results programmatically.

Anatomy of the Standardized Output Dictionary

Every Holehe module returns a Python dictionary following an identical schema. This consistency allows the core controller to aggregate results without service-specific parsing logic.

The dictionary contains the following fields:

• module (str): The identifier for the service being checked (e.g., instagram, github, twitter).
• email (str): The email address submitted for verification.
• username (str): The discovered username on the target platform, if available.
• url (str): The direct URL to the profile page when the service exposes public profile links.
• exist (bool): Boolean flag indicating whether the account was positively confirmed (True) or not found/absent (False).
• error (str, optional): Human-readable error message when network issues or rate limiting prevent completion of the check.

Modules populate only relevant fields. For example, in holehe/modules/social_media/instagram.py, the module omits the url key if no public profile link exists, while setting exist to False and including an error string when the service is unreachable.

Core Aggregation Logic in holehe/core.py

The central runner located at holehe/core.py collects all module results into a list of dictionaries. Each module registers its execution function via holehe/modules/**/__init__.py and returns the standardized schema upon completion.

When displaying results to the console, the core controller formats the standardized dictionaries as:

[+] ModuleName → Username (URL)

For accounts that cannot be found or verified, the output appears as:

[!] ModuleName → Not found

This formatting logic examines the exist boolean to determine which symbol to display, then extracts the username and url fields for successful matches.

Module-Specific Field Population Strategies

Different services expose varying data points, requiring flexible yet standardized field population.

Profile-Heavy Services: In holehe/modules/social_media/instagram.py, modules typically return all fields including url when exist is True, providing direct links to discovered accounts.

Software Platforms: Services like GitHub, implemented in holehe/modules/software/github.py, follow the same dictionary structure but may emphasize the username field while conditionally including url based on API response availability.

Error Handling: When modules encounter network timeouts or API restrictions, they return exist=False with the error field populated, allowing the core runner to distinguish between "account not found" and "check failed."

Practical Implementation Examples

Accessing Holehe's standardized output programmatically requires importing the core class and iterating through the returned list.

from holehe.core import Holehe

email = "test@example.com"
holehe = Holehe(email)

# Execute all modules and retrieve standardized dictionaries

results = holehe.run()

for result in results:
    if result["exist"]:
        print(f"[+] {result['module']} → {result.get('username', '')} ({result.get('url', '')})")
    else:
        print(f"[!] {result['module']} → Not found")

Command-line usage produces identical formatting through the same aggregation pipeline:

$ holehe -u test@example.com
[+] instagram → testuser (https://instagram.com/testuser)
[+] twitter   → Not found
[+] github    → testuser (https://github.com/testuser)

Summary

• Holehe modules return unified dictionaries with consistent fields: module, email, username, url, exist, and optional error.
• The exist boolean drives display logic, determining whether the console shows a successful match or failure indicator.
• File holehe/core.py aggregates results into a list and handles terminal formatting using [+] and [!] prefixes.
• Optional fields allow flexibility while maintaining schema consistency across diverse service implementations like instagram.py and github.py.

Frequently Asked Questions

What fields are mandatory in Holehe's standardized output dictionary?

Every module must return the module, email, and exist fields. The username, url, and error fields are optional and populated only when relevant to the specific service or when errors occur during execution.

How does Holehe distinguish between "account not found" and "check failed"?

The exist boolean indicates account status, while the optional error string clarifies execution failures. When exist is False and error is absent, the account does not exist. When exist is False and error is present, the module encountered a network or API issue.

Can Holehe results be parsed as JSON for integration with other tools?

Yes. Since holehe/core.py aggregates results into a list of standard Python dictionaries, you can serialize the output directly to JSON. Each dictionary follows the same schema regardless of the module source, enabling reliable parsing with tools like jq or import into databases.

Where is the console output formatting defined in the Holehe codebase?

The formatting logic resides in holehe/core.py, which processes the standardized module dictionaries and prints [+] ModuleName for existing accounts and [!] ModuleName for non-existent accounts or errors, extracting username and url values where available.

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