# Holehe Module Result Dictionary: Complete Schema and Usage Guide

> Explore the Holehe module result dictionary schema and understand its usage. Learn about name, rateLimit, exists, emailrecovery, phoneNumber, and others.

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

---

**Every Holehe module returns a standard Python dictionary with six fixed keys: `name`, `rateLimit`, `exists`, `emailrecovery`, `phoneNumber`, and `others`.**

The Holehe osint (Open Source Intelligence) tool, developed by megadose, uses a consistent result format across all 120+ modules to report whether an email address is registered on various online services. This article explains the Holehe module result dictionary schema, shows how to access each field programmatically, and provides working code examples from the actual source code.

## What Is the Holehe Module Result Dictionary

When you run Holehe—either from the command line or as a Python library—each service check produces a single dictionary. Every module in `holehe/modules/` follows this exact pattern, making it easy to aggregate and analyze results across dozens of platforms.

The dictionary serves as the universal data contract between individual modules and the reporting engine in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). Regardless of whether you're checking Twitter, Instagram, or a niche transport service like BlaBlaCar, the output structure remains identical.

## The Six Fields in Every Holehe Result Dictionary

| Key | Type | Description |
|-----|------|-------------|
| **`name`** | `str` | Module identifier matching the service (e.g., `twitter`, `instagram`, `blablacar`). |
| **`rateLimit`** | `bool` | `True` if the service blocked the request due to rate limiting. |
| **`exists`** | `bool` | `True` if the email is registered on that service. |
| **`emailrecovery`** | `str` or `None` | Partially masked recovery email, if exposed by the service. |
| **`phoneNumber`** | `str` or `None` | Partially masked recovery phone number, if exposed. |
| **`others`** | `any` or `None` | Extension point for additional module-specific data. |

This schema is documented in the repository's README under the **Module Output** section and enforced by convention across all module implementations.

## Where the Result Dictionary Is Built in the Source Code

### Core Implementation Pattern

Each Holehe module constructs its result dictionary at the end of its main function. For example, in [`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/twitter.py) and [`holehe/modules/transport/blablacar.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/transport/blablacar.py), you'll see code following this pattern:

```python
out.append({
    "name": "twitter",
    "rateLimit": is_rate_limited,
    "exists": account_found,
    "emailrecovery": masked_email,
    "phoneNumber": masked_phone,
    "others": None
})

```

The `out` parameter is a list passed by the caller (managed in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)) that collects all result dictionaries for final aggregation.

### Key Source Files

- **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)** – Orchestrates module execution and aggregates dictionaries into reports.
- **[`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/twitter.py)** – Social media module implementing the result format.
- **[`holehe/modules/transport/blablacar.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/transport/blablacar.py)** – Transport module with identical dictionary construction.
- **[`README.md`](https://github.com/megadose/holehe/blob/main/README.md)** – Documents the expected output structure for contributors and users.

## Working with Holehe Result Dictionaries in Python

### Basic Programmatic Usage

```python
import httpx
import trio
from holehe.modules.social_media.twitter import twitter

async def check_single_service(email: str):
    results = []
    
    async with httpx.AsyncClient() as client:
        await twitter(email, client, results)
    
    # Returns the standard 6-key dictionary

    return results[0]

# Execute

result = trio.run(check_single_service, "test@example.com")
print(result)

```

Expected output:

```python
{
    'name': 'twitter',
    'rateLimit': False,
    'exists': True,
    'emailrecovery': None,
    'phoneNumber': None,
    'others': None
}

```

### Processing Multiple Results

```python
from holehe.core import import_submodules
from holehe.modules import module

async def check_email_full(email: str):
    async with httpx.AsyncClient() as client:
        modules = import_submodules()
        all_results = []
        
        for mod in modules:
            out = []
            try:
                await mod(email, client, out)
                all_results.extend(out)
            except Exception:
                continue  # Skip failed modules

        
        # Filter and analyze results

        found_accounts = [r for r in all_results if r['exists']]
        rate_limited = [r for r in all_results if r['rateLimit']]
        
        return {
            'total_checked': len(all_results),
            'accounts_found': len(found_accounts),
            'rate_limited_services': [r['name'] for r in rate_limited],
            'recovery_emails': [r['emailrecovery'] for r in all_results if r['emailrecovery']]
        }

```

### Checking for Recovery Information

The `emailrecovery` and `phoneNumber` fields are particularly valuable for osint investigations. Services like Instagram occasionally expose partial recovery data:

```python
async def check_recovery_data(email: str):
    from holehe.modules.social_media.instagram import instagram
    
    results = []
    async with httpx.AsyncClient() as client:
        await instagram(email, client, results)
    
    result = results[0]
    
    if result['exists']:
        print(f"Account found on {result['name']}")
        
        if result['emailrecovery']:
            print(f"  Recovery email pattern: {result['emailrecovery']}")
            # Example output: "ex****e@gmail.com"

        
        if result['phoneNumber']:
            print(f"  Recovery phone pattern: {result['phoneNumber']}")
            # Example output: "0*******78"

    
    return result

```

## Interpreting Field Values Correctly

### Understanding `rateLimit` vs `exists`

These boolean flags operate independently:

- **`rateLimit: True`** – The service blocked the request; `exists` is unreliable.
- **`exists: True`** – Confirmed registration, but check if `rateLimit` is `False`.
- Both `False` – Confirmed no account found (or service unavailable).

Always check `rateLimit` before trusting `exists`:

```python
def is_confirmed_account(result: dict) -> bool:
    return result['exists'] and not result['rateLimit']

```

### The `others` Extension Field

While currently `None` in most modules, `others` allows future expansion without breaking the schema. Custom modules can use it to return:
- Profile URLs
- Username handles
- Account creation dates
- Geo-location hints

Maintain backward compatibility by keeping the six core fields present even when extending.

## Summary

- Every Holehe module returns **identical dictionary keys**: `name`, `rateLimit`, `exists`, `emailrecovery`, `phoneNumber`, and `others`.
- The schema is **enforced by convention** across all modules in `holehe/modules/` and documented in [`README.md`](https://github.com/megadose/holehe/blob/main/README.md).
- **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)** orchestrates execution while individual service modules in `social_media/`, `transport/`, and other categories implement the format.
- **Programmatic access** requires passing an `out` list that receives result dictionaries; use `httpx.AsyncClient` for HTTP handling.
- **Recovery data fields** (`emailrecovery`, `phoneNumber`) contain masked patterns, not full credentials.
- **Always validate `rateLimit`** before trusting positive `exists` results.

## Frequently Asked Questions

### What does `rateLimit: True` mean in a Holehe result dictionary?

A `True` value indicates the target service blocked the request due to too many queries from your IP address. When `rateLimit` is `True`, the `exists` field becomes unreliable—you cannot determine whether the account exists because the service refused to respond. Wait before retrying or rotate your IP address.

### Can Holehe result dictionaries contain additional custom keys?

No. All modules must return exactly the six specified keys to maintain compatibility with [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and downstream tools. The `others` field exists specifically for extensibility—place any supplementary data there rather than adding new top-level keys.

### How do I extract just the services where an account exists?

Filter the results list using a list comprehension that checks both `exists` and `rateLimit`:

```python
confirmed = [
    r['name'] for r in results 
    if r['exists'] and not r['rateLimit']
]

```

This pattern appears throughout the Holehe codebase when generating summary reports.