.. _library-usage:

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

.. code-block:: bash

pip install maigret

Minimal example

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

.. code-block:: python

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:

.. code-block:: python

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:

.. code-block:: python

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:

.. code-block:: python

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

.. code-block:: python

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 :doc:command-line-options for a description of each option — the semantics match the CLI flags one-to-one.