Library usage

Maigret’s CLI is a thin wrapper around an async Python API. You can embed Maigret in your own tools, pipelines, and OSINT workflows — no need to shell out.

This page covers the common patterns. For the full argument list of the underlying function, see maigret.checking.maigret in the source.

Installation

pip install maigret

Minimal example

A working end-to-end search against the top 500 sites:

import asyncio
import logging

from maigret import search as maigret_search
from maigret.sites import MaigretDatabase

# Load the bundled site database
db = MaigretDatabase().load_from_path(
    "maigret/resources/data.json"
)

# Pick which sites to scan (same filtering the CLI uses)
sites = db.ranked_sites_dict(top=500)

results = asyncio.run(
    maigret_search(
        username="soxoj",
        site_dict=sites,
        logger=logging.getLogger("maigret"),
        timeout=30,
        is_parsing_enabled=True,
    )
)

for site_name, result in results.items():
    if result["status"].is_found():
        print(site_name, result["url_user"])

Key points:

maigret_search is an async function — wrap it with asyncio.run(...) or await it from inside your own event loop.
is_parsing_enabled=True turns on socid_extractor so result["ids_data"] is populated with profile fields (bio, linked accounts, uids, etc.).
Each entry in the returned dict has a "status" object with is_found(), plus url_user, http_status, rank, ids_data, and more.

Filtering sites

ranked_sites_dict accepts the same filters as the CLI:

# All sites tagged as coding, top 200 by rank
sites = db.ranked_sites_dict(top=200, tags=["coding"])

# Exclude NSFW and dating sites
sites = db.ranked_sites_dict(excluded_tags=["nsfw", "dating"])

# Only specific sites by name
sites = db.ranked_sites_dict(names=["GitHub", "Reddit", "VK"])

# Include disabled sites (useful for maintenance / self-check)
sites = db.ranked_sites_dict(disabled=True)

Running inside an existing event loop

If your application already runs an asyncio loop (FastAPI, aiohttp server, a Discord bot, etc.), await maigret_search directly instead of calling asyncio.run:

async def check_username(username: str) -> dict:
    results = await maigret_search(
        username=username,
        site_dict=sites,
        logger=logger,
        timeout=30,
    )
    return {
        name: r["url_user"]
        for name, r in results.items()
        if r["status"].is_found()
    }

Routing through a proxy

The same proxy / Tor / I2P flags the CLI exposes are plain keyword arguments:

results = await maigret_search(
    username="soxoj",
    site_dict=sites,
    logger=logger,
    proxy="socks5://127.0.0.1:1080",
    tor_proxy="socks5://127.0.0.1:9050",   # used for .onion sites
    i2p_proxy="http://127.0.0.1:4444",     # used for .i2p sites
    timeout=30,
)

Full function signature

async def maigret(
    username: str,
    site_dict: Dict[str, MaigretSite],
    logger,
    query_notify=None,
    proxy=None,
    tor_proxy=None,
    i2p_proxy=None,
    timeout=30,
    is_parsing_enabled=False,
    id_type="username",
    debug=False,
    forced=False,
    max_connections=100,
    no_progressbar=False,
    cookies=None,
    retries=0,
    check_domains=False,
) -> QueryResultWrapper

See Command line options for a description of each option — the semantics match the CLI flags one-to-one.