# What Is the Standard Schema for Holehe Results? A Complete Technical Guide

> Understand the standard schema for Holehe results with this technical guide. Learn about the eight key fields ensuring uniform output for all website modules, regardless of status.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: deep-dive
- Published: 2026-08-26

---

**Holehe returns a standardized list of dictionaries containing eight specific fields—`name`, `domain`, `exists`, `rateLimit`, `error`, `emailrecovery`, `phoneNumber`, and `others`—ensuring uniform output across all website modules regardless of success or failure states.**

Holehe is an open-source email reconnaissance tool developed by megadose that checks whether an email address is registered across hundreds of websites. Understanding the standard schema for Holehe results is essential for building automated workflows, parsing JSON outputs, and processing CSV exports consistently. This schema acts as a contract between the individual site modules and the core orchestration logic, guaranteeing that every probe returns a predictable data structure.

## The Eight-Field Holehe Result Schema

Every website check performed by Holehe generates a dictionary with exactly eight keys. This fixed structure allows the CLI and programmatic consumers to process results without conditional logic for missing fields.

### Core Identity Fields

- **`name`** (`str`): The internal identifier of the module performing the check (e.g., `twitter`, `github`, `instagram`).
- **`domain`** (`str`): The human-readable website domain (e.g., `twitter.com`, `github.com`).

These fields provide immediate context about which service was queried, appearing first in CLI outputs and serving as primary keys in CSV exports.

### Status Indicators

Three boolean flags communicate the outcome of each request:

- **`exists`** (`bool`): **True** when the email address is registered on the target site; **False** if the account does not exist or if the check was inconclusive.
- **`rateLimit`** (`bool`): **True** when the target website rejected the request due to rate limiting, preventing a definitive answer.
- **`error`** (`bool`): **True** if an unexpected exception occurred during the module execution (network errors, parsing failures, site changes).

According to the source code in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), these booleans are mutually prioritized: if `error` or `rateLimit` is **True**, the `exists` field should be interpreted with caution.

### Recovery Metadata

When available, Holehe extracts account recovery information leaked by the website's password reset flow:

- **`emailrecovery`** (`str | None`): Information returned by the site's recovery mechanism, such as masked email addresses (e.g., `a***@gmail.com`) or confirmation messages.
- **`phoneNumber`** (`str | None`): Partial or complete phone numbers associated with the account, if the module successfully extracts them from recovery pages.

Not all modules populate these fields, and many return `None` when the site does not expose recovery information or when the check fails.

### Extensibility Container

- **`others`** (`dict | None`): A flexible dictionary for module-specific data that does not fit standard fields. Common entries include `FullName`, account creation dates, profile URLs, or custom error messages.

This field prevents schema fragmentation, allowing developers to expose new data points without breaking existing parsers that rely on the eight-field structure.

## Where the Schema Is Implemented in the Source Code

The standard schema is defined implicitly through consistent usage across [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), specifically within three critical functions:

- **`launch_module`** (line ≈ 171): When a module raises an exception, this function constructs a fallback dictionary conforming to the schema, setting `error` to **True** and populating remaining fields with default values. This guarantees that even failed checks return valid records.
- **`export_csv`**: This function uses `data[0].keys()` to write CSV headers, confirming that the first result's dictionary keys define the fixed column order for all exports.
- **`print_result`**: The CLI formatting logic reads the same eight keys to generate color-coded terminal output, mapping `exists` to green/red indicators and highlighting `rateLimit` warnings.

Individual modules in `holehe/modules/**/*.py` populate these dictionaries by returning the eight-field structure at the end of their execution flow.

## Working with Holehe Results Programmatically

### Basic Command-Line Usage

Generate CSV output containing the standard schema:

```bash
holehe user@example.com --csv

```

This command creates a color-coded terminal table and writes `holehe_<timestamp>_user@example.com_results.csv` with columns matching the eight-field schema exactly.

### Parsing Results in Python

When importing Holehe as a library or processing saved JSON, treat the output as a list of dictionaries:

```python
import json

# Example result set returned by Holehe

results = [
    {
        "name": "twitter",
        "domain": "twitter.com",
        "exists": True,
        "rateLimit": False,
        "error": False,
        "emailrecovery": "Password reset link sent",
        "phoneNumber": None,
        "others": {"FullName": "Jane Doe", "username": "janedoe"}
    },
    {
        "name": "github",
        "domain": "github.com",
        "exists": False,
        "rateLimit": False,
        "error": False,
        "emailrecovery": None,
        "phoneNumber": None,
        "others": None
    }
]

# Extract domains where the email exists

confirmed_sites = [r["domain"] for r in results if r["exists"]]
print(f"Email found on: {confirmed_sites}")

```

### Filtering for Valid Registrations Only

Exclude rate-limited responses and errors to analyze confirmed accounts:

```python
def get_valid_accounts(data):
    """Filter results to return only confirmed registrations without errors."""
    return [
        r for r in data 
        if r["exists"] and not r["error"] and not r["rateLimit"]
    ]

valid_accounts = get_valid_accounts(results)
print(f"Valid registrations: {len(valid_accounts)}")

```

### Accessing Extended Metadata

Inspect the `others` field for additional intelligence gathered by specific modules:

```python
for result in results:
    if result["others"] and "FullName" in result["others"]:
        print(f"{result['domain']}: {result['others']['FullName']}")

```

## Summary

- **Fixed Structure**: Every Holehe result contains exactly eight fields: `name`, `domain`, `exists`, `rateLimit`, `error`, `emailrecovery`, `phoneNumber`, and `others`.
- **Guaranteed Consistency**: The `launch_module` function in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) enforces this schema even when modules crash or hit rate limits, ensuring no `KeyError` exceptions in downstream processing.
- **CSV Compatibility**: The `export_csv` function relies on the schema's uniformity to generate headers dynamically from the first result's keys.
- **Extensibility**: The `others` dictionary allows modules to expose custom data without breaking the standard contract.
- **Boolean Logic**: Always check `error` and `rateLimit` before trusting the `exists` field to avoid false positives.

## Frequently Asked Questions

### What happens when a module fails or hits a rate limit?

Holehe returns a complete dictionary conforming to the standard schema regardless of outcome. If a module raises an exception, `error` is set to **True** and `exists` defaults to **False**. If a rate limit is detected, `rateLimit` becomes **True**. This design, implemented in the exception handler at line ≈ 171 of [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), ensures your parsing logic never encounters missing keys.

### How do I export Holehe results to CSV format?

Use the `--csv` flag when running from the command line: `holehe user@example.com --csv`. The tool writes a timestamped CSV file where headers are derived from the first result's dictionary keys (`data[0].keys()`), guaranteeing alignment with the eight-field schema. You can also process the JSON output programmatically and use Python's `csv.DictWriter` to maintain the same column order.

### Can I add custom fields to the Holehe result schema?

No, you should not add top-level fields to the standard schema, as this would break CSV exports and CLI formatting in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). Instead, place custom data inside the `others` dictionary. This container accepts any serializable dictionary without affecting the fixed eight-field structure that downstream tools expect.

### How do I filter only confirmed email registrations from the output?

Iterate through the results list and check three conditions: `exists` must be **True**, while `error` and `rateLimit` must both be **False**. This excludes inconclusive results caused by network failures or anti-bot protections, yielding only verified account registrations.