# Understanding the JSON Output Format for Holehe Results

> Decode Holehe results with our guide to the JSON output format. Understand standardized keys like name, exists, and rateLimit for email verification.

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

---

**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`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and individual modules like [`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/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:

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

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

```python
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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/holehe/core.py)**: Orchestrates module execution and aggregates the final list of result dictionaries
- **[`holehe/modules/social_media/twitter.py`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/README.md)**: Documents the JSON structure under the *Module Output* section
- **[`holehe/__init__.py`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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.