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

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, 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.

# 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, 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.

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.

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 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 – Contains the CLI entry point, argument parsing via maincore(), and module orchestration logic including import_submodules() and get_functions()
• 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 – 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}