# Holehe Module Results Output Format: Complete Schema and Usage Guide

> Understand the holehe module results output format. Learn about the standardized Python dictionary with ten keys like exists, rateLimit, and emailrecovery for automated OSINT.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: api-reference
- Published: 2026-08-22

---

**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`](https://github.com/megadose/holehe/blob/main/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:

```json
{
  "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`](https://github.com/megadose/holehe/blob/main/holehe/core.py)

The `print_result` function in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/megadose/holehe/blob/main/holehe/core.py):

```python
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`](https://github.com/megadose/holehe/blob/main/holehe/core.py) (lines 22-48) and implemented in modules like [`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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.