# Standardized Output Format for Holehe Module Results: Complete Schema Guide

> Explore the standardized output format for Holehe module results. Understand the schema including module, email, username, url, exist, and error fields for programmatic processing.

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

---

**Holehe modules return a unified dictionary containing `module`, `email`, `username`, `url`, `exist`, and optional `error` fields, which the core runner aggregates into a list for consistent programmatic processing.**

The megadose/holehe repository provides an open-source email OSINT framework for checking account existence across hundreds of services. Understanding the standardized output format is essential for developers integrating Holehe into automated workflows or parsing results programmatically.

## Anatomy of the Standardized Output Dictionary

Every Holehe module returns a Python dictionary following an identical schema. This consistency allows the core controller to aggregate results without service-specific parsing logic.

The dictionary contains the following fields:

- **`module`** (`str`): The identifier for the service being checked (e.g., `instagram`, `github`, `twitter`).
- **`email`** (`str`): The email address submitted for verification.
- **`username`** (`str`): The discovered username on the target platform, if available.
- **`url`** (`str`): The direct URL to the profile page when the service exposes public profile links.
- **`exist`** (`bool`): Boolean flag indicating whether the account was positively confirmed (`True`) or not found/absent (`False`).
- **`error`** (`str`, optional): Human-readable error message when network issues or rate limiting prevent completion of the check.

Modules populate only relevant fields. For example, in [`holehe/modules/social_media/instagram.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/instagram.py), the module omits the `url` key if no public profile link exists, while setting `exist` to `False` and including an `error` string when the service is unreachable.

## Core Aggregation Logic in holehe/core.py

The central runner located at [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) collects all module results into a list of dictionaries. Each module registers its execution function via `holehe/modules/**/__init__.py` and returns the standardized schema upon completion.

When displaying results to the console, the core controller formats the standardized dictionaries as:

```

[+] ModuleName → Username (URL)

```

For accounts that cannot be found or verified, the output appears as:

```

[!] ModuleName → Not found

```

This formatting logic examines the `exist` boolean to determine which symbol to display, then extracts the `username` and `url` fields for successful matches.

## Module-Specific Field Population Strategies

Different services expose varying data points, requiring flexible yet standardized field population.

**Profile-Heavy Services**: In [`holehe/modules/social_media/instagram.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/instagram.py), modules typically return all fields including `url` when `exist` is `True`, providing direct links to discovered accounts.

**Software Platforms**: Services like GitHub, implemented in [`holehe/modules/software/github.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/software/github.py), follow the same dictionary structure but may emphasize the `username` field while conditionally including `url` based on API response availability.

**Error Handling**: When modules encounter network timeouts or API restrictions, they return `exist=False` with the `error` field populated, allowing the core runner to distinguish between "account not found" and "check failed."

## Practical Implementation Examples

Accessing Holehe's standardized output programmatically requires importing the core class and iterating through the returned list.

```python
from holehe.core import Holehe

email = "test@example.com"
holehe = Holehe(email)

# Execute all modules and retrieve standardized dictionaries

results = holehe.run()

for result in results:
    if result["exist"]:
        print(f"[+] {result['module']} → {result.get('username', '')} ({result.get('url', '')})")
    else:
        print(f"[!] {result['module']} → Not found")

```

Command-line usage produces identical formatting through the same aggregation pipeline:

```bash
$ holehe -u test@example.com
[+] instagram → testuser (https://instagram.com/testuser)
[+] twitter   → Not found
[+] github    → testuser (https://github.com/testuser)

```

## Summary

- **Holehe modules return unified dictionaries** with consistent fields: `module`, `email`, `username`, `url`, `exist`, and optional `error`.
- **The `exist` boolean drives display logic**, determining whether the console shows a successful match or failure indicator.
- **File [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) aggregates results** into a list and handles terminal formatting using `[+]` and `[!]` prefixes.
- **Optional fields allow flexibility** while maintaining schema consistency across diverse service implementations like [`instagram.py`](https://github.com/megadose/holehe/blob/main/instagram.py) and [`github.py`](https://github.com/megadose/holehe/blob/main/github.py).

## Frequently Asked Questions

### What fields are mandatory in Holehe's standardized output dictionary?

Every module must return the `module`, `email`, and `exist` fields. The `username`, `url`, and `error` fields are optional and populated only when relevant to the specific service or when errors occur during execution.

### How does Holehe distinguish between "account not found" and "check failed"?

The `exist` boolean indicates account status, while the optional `error` string clarifies execution failures. When `exist` is `False` and `error` is absent, the account does not exist. When `exist` is `False` and `error` is present, the module encountered a network or API issue.

### Can Holehe results be parsed as JSON for integration with other tools?

Yes. Since [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) aggregates results into a list of standard Python dictionaries, you can serialize the output directly to JSON. Each dictionary follows the same schema regardless of the module source, enabling reliable parsing with tools like `jq` or import into databases.

### Where is the console output formatting defined in the Holehe codebase?

The formatting logic resides in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), which processes the standardized module dictionaries and prints `[+] ModuleName` for existing accounts and `[!] ModuleName` for non-existent accounts or errors, extracting `username` and `url` values where available.