# Holehe API: How to Use Holehe Programmatically Without a REST Interface

> Integrate OSINT email checking into your apps with the Holehe Python API. Learn how to use its async functions programmatically, bypassing the need for a REST interface. Check emails directly from your code.

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

---

**Holehe does not expose a public HTTP or REST API; instead, it provides a Python API through importable async functions that allow you to embed OSINT email checking directly into your applications.**

Holehe is an open-source OSINT tool developed by megadose that checks if an email address is registered on various websites. While it is primarily distributed as a command-line interface, the codebase is structured as a Python library with a programmatic API accessible through direct module imports. You can leverage this Python API to integrate email-to-account correlation capabilities into custom scripts and automated workflows.

## How the Holehe Python API Works

The core orchestration logic lives in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), which handles argument parsing, module discovery, and concurrent execution. Rather than exposing network endpoints, Holehe functions as an embeddable library where you import async Python functions directly from the `holehe` package.

The entry point for CLI operations is `holehe.core.main()`, which invokes the async `maincore()` routine using `trio.run(maincore)`. This function handles the heavy lifting of loading detection modules and running them concurrently.

Module discovery happens through `import_submodules("holehe.modules")`, which dynamically imports every detection module located in the `holehe/modules/` directory. The `get_functions()` utility then extracts callable async functions from these modules, returning a list of functions that each represent a specific service check (e.g., Snapchat, Instagram).

## Using the Holehe CLI

The simplest way to interact with Holehe is through the command-line interface, which wraps the underlying Python API.

```bash

# Install holehe from PyPI

pip install holehe

# Run it against an email address

holehe test@example.com

```

When you execute the `holehe` command, it triggers the logic in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), specifically the `main()` function that orchestrates the async execution environment.

## Embedding Holehe in Python Scripts

To use Holehe programmatically, import the core utilities and run the detection modules within your own async context. This approach gives you full control over the execution flow and result handling.

```python
import trio
import httpx
from holehe.core import import_submodules, get_functions

async def run_holehe(email: str):
    # Load all detection modules

    modules = import_submodules("holehe.modules")
    websites = get_functions(modules)          # returns list of async callables

    client = httpx.AsyncClient(timeout=10)
    results = []
    async with trio.open_nursery() as nursery:
        for mod in websites:
            nursery.start_soon(mod, email, client, results)

    await client.aclose()
    return results

if __name__ == "__main__":
    email = "test@example.com"
    result = trio.run(run_holehe, email)
    for entry in result:
        print(entry)

```

This script replicates the CLI behavior by:
- Calling `import_submodules("holehe.modules")` to discover every module under `holehe/modules`
- Extracting functions via `get_functions(modules)`
- Executing each service check concurrently using `trio.open_nursery()`

Each module follows a consistent async signature `(email, client, out)` and appends a dictionary to the `out` list containing fields like `exists`, `rateLimit`, and `source`.

## Calling Individual Modules Directly

If you only need to check a specific service rather than running all modules, import the function directly from its location in the `holehe/modules/` hierarchy.

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

async def check_instagram(email: str):
    async with httpx.AsyncClient(timeout=10) as client:
        out = []
        await instagram(email, client, out)
        return out[0]   # contains the result dict

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

```

This pattern is useful when you need granular control over which services to query or when integrating specific checks into larger data processing pipelines. Individual detection routines are defined in files like [`holehe/modules/social_media/snapchat.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/snapchat.py) and follow the same `(email, client, out)` parameter pattern.

## Core Architecture and Key Files

Understanding the repository structure helps when working with the Holehe API programmatically:

- **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)** – Contains the CLI entry point, argument parsing via `maincore()`, and module orchestration logic including `import_submodules()` and `get_functions()`
- **[`holehe/__init__.py`](https://github.com/megadose/holehe/blob/main/holehe/__init__.py)** – Package initialization that exposes the `main` entry point
- **`holehe/modules/*/*.py`** – Individual service detection modules, each containing async functions like `snapchat()` or `instagram()` that implement specific site checks
- **[`holehe/modules/social_media/snapchat.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/snapchat.py)** – Example implementation showing the standard detection pattern using `httpx.AsyncClient`

## Summary

- Holehe provides a **Python API**, not a REST or HTTP API, for programmatic access
- The primary interface is through async functions in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) and individual modules under `holehe/modules/`
- Use `import_submodules("holehe.modules")` and `get_functions()` to dynamically load all service checks
- Individual detection functions accept three parameters: `email`, `httpx.AsyncClient`, and an output list
- The library uses **Trio** for async concurrency and **httpx** for HTTP requests
- You can import specific service functions directly (e.g., from `holehe.modules.social_media.instagram`) to check individual platforms

## Frequently Asked Questions

### Does Holehe have a REST API?

No, Holehe does not expose a REST, HTTP, or web API. According to the megadose/holehe source code, the tool is designed as a command-line utility and Python library. All functionality is accessed through Python function imports and async method calls rather than network endpoints.

### How do I import Holehe into my Python script?

Import the core utilities from `holehe.core` (specifically `import_submodules` and `get_functions`) to load all detection modules, or import individual service functions directly from their paths (e.g., `from holehe.modules.social_media.instagram import instagram`). You will need to run these async functions within a Trio event loop.

### What parameters do Holehe detection functions require?

Each detection function follows the signature `async def servicename(email, client, out)` where `email` is the target string, `client` is an `httpx.AsyncClient` instance for making HTTP requests, and `out` is a list where the function appends a dictionary containing the results. This structure is consistent across all modules in `holehe/modules/`.

### Can I use Holehe without installing the CLI?

Yes, you can use Holehe purely as a library dependency without invoking the command-line interface. Install it via pip, import the necessary modules from `holehe.core` or specific service files, and call the async functions directly from your Python code using Trio. This allows integration into web applications, data pipelines, or automated OSINT scripts without shell execution.