Understanding the JSON Output Format for Holehe Results

Holehe returns email verification results as a JSON-compatible list of dictionaries, with each service check populating standardized keys including name, exists, rateLimit, emailrecovery, phoneNumber, and others.

Holehe is an open-source email investigation tool that checks if an address is registered across various online services. When analyzing accounts with the megadose/holehe repository, understanding the JSON output format for Holehe results is essential for parsing findings programmatically and integrating them into security workflows.

Structure of the JSON Output

Each module in Holehe returns results as a JSON-compatible dictionary containing a standardized set of keys. According to the source code in holehe/core.py and individual modules like holehe/modules/social_media/twitter.py, these dictionaries follow a consistent schema across all services.

Core Dictionary Keys

Every result dictionary includes the following required fields:

• name: The internal identifier of the module (e.g., twitter, instagram)
• rateLimit: Boolean (true or false) indicating if the request encountered rate limiting
• exists: Boolean indicating whether the email is registered on the service (true) or not (false)
• emailrecovery: Partially obfuscated recovery email address (e.g., ex****e@gmail.com) or null if unavailable
• phoneNumber: Partially obfuscated recovery phone number (e.g., 0*******78) or null if unavailable
• others: Additional information provided by specific modules or null

Optional keys used by certain modules include:

• method: The interaction type employed (values like register, login, etc.)
• frequent_rate_limit: Boolean flag for services that commonly trigger rate limits

Result Aggregation Format

Holehe aggregates individual module results into a JSON array (list) containing all dictionary objects. When running the complete suite, the final output structure appears as:

[
  {
    "name": "twitter",
    "rateLimit": false,
    "exists": true,
    "emailrecovery": null,
    "phoneNumber": null,
    "others": null
  },
  {
    "name": "instagram",
    "rateLimit": false,
    "exists": false,
    "emailrecovery": null,
    "phoneNumber": null,
    "others": null
  }
]

This list structure is generated in holehe/core.py, which orchestrates module execution and collects results from each service check into a single Python list that serializes directly to JSON.

Working with Holehe JSON Output

Capturing JSON from the Command Line

While the CLI defaults to human-readable tables, you can capture the underlying JSON structure by redirecting stdout to a file:

holehe test@example.com > results.json

The application writes Python dictionaries that are JSON-serializable, allowing direct parsing with standard JSON tools.

Extracting JSON via Python Embedding

When embedding Holehe modules directly in Python, you collect results by passing a list object that each module appends to:

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

async def main():
    email = "test@example.com"
    out = []                                   # List to hold JSON-compatible dicts

    client = httpx.AsyncClient()
    await twitter(email, client, out)          # Module appends its result dictionary

    await instagram(email, client, out)
    await client.aclose()
    print(out)                                 # Python list of dictionaries

trio.run(main)

Each module in holehe/modules/ follows this pattern, accepting the output list as a parameter and appending the standardized dictionary upon completion.

Converting to CSV

The same JSON data structure powers Holehe's CSV export functionality. In holehe/core.py, the export_csv function processes the list of dictionaries generated during execution, transforming the JSON-compatible objects into tabular format while preserving all key-value pairs.

Source Code Implementation

The JSON output format is defined across several key files in the megadose/holehe repository:

• holehe/core.py: Orchestrates module execution and aggregates the final list of result dictionaries
• holehe/modules/social_media/twitter.py: Example implementation showing dictionary construction with keys including name, domain, method, rateLimit, exists, emailrecovery, phoneNumber, and others
• README.md: Documents the JSON structure under the Module Output section
• holehe/__init__.py: Exposes the CLI entry point while maintaining the internal JSON generation pipeline

Summary

• Holehe returns results as a list of JSON-compatible dictionaries, with one entry per checked service
• Each dictionary contains standardized keys: name, rateLimit, exists, emailrecovery, phoneNumber, and others
• Optional fields like method and frequent_rate_limit may appear depending on the specific module
• The aggregation logic in holehe/core.py collects outputs from all modules into a serializable JSON array
• Results can be captured via CLI redirection, Python embedding, or converted to CSV using the same underlying data structure

Frequently Asked Questions

What keys are included in each Holehe result dictionary?

Every result includes name (module identifier), rateLimit (boolean), exists (boolean indicating registration status), emailrecovery (obfuscated email or null), phoneNumber (obfuscated phone or null), and others (additional data or null). Optional fields include method and frequent_rate_limit for specific services.

How do I save Holehe output as a JSON file?

Redirect the CLI output to a file using standard shell redirection: holehe email@example.com > output.json. While the CLI displays formatted tables by default, the underlying data structure serialized to stdout is JSON-compatible.

Can I parse Holehe results programmatically in Python?

Yes. Import individual modules from holehe.modules and pass an empty list to collect results. Each module appends a dictionary to this list, which you can then serialize using Python's json module or process as native Python dictionaries.

What is the difference between rateLimit and frequent_rate_limit?

The rateLimit key indicates whether the specific request triggered a rate limit (boolean), while frequent_rate_limit is an optional flag marking services that are known to commonly impose rate limits across all queries.

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