# Pro lookup
Source: https://docs.leakcheck.io/api-reference/pro-api-v2/pro-lookup

https://leakcheck.io/openapi.json get /api/v2/query/{query}
Search full breach records by email, username, phone number, domain, hash and more. Requires an [API key](https://docs.leakcheck.io/authentication) passed either in the `X-API-Key` header (recommended) or as the `?key=` query parameter.



# Public lookup
Source: https://docs.leakcheck.io/api-reference/public-api/public-lookup

https://leakcheck.io/openapi.json get /api/public
Free, unauthenticated lookup. Returns which breaches an identifier appears in and which data categories were exposed — never the values themselves. Use the Pro API for full records. Rate limited to 1 request per second.



# Authentication
Source: https://docs.leakcheck.io/authentication

How to authenticate requests to the LeakCheck Pro API v2.

Every Pro API v2 endpoint requires an API key. The Public API needs no
authentication.

## Getting an API key

You can obtain your personal API key in your
[account settings](https://leakcheck.io) on leakcheck.io. Keys are at least
40 characters long.

## Passing the key

There are two ways to authenticate a request:

1. **Header (recommended)** — send the key in the `X-API-Key` header:

```text theme={null}
Accept: application/json
X-API-Key: 8cb2237d0679ca88db6464eac60da96345513964
```

2. **Query parameter** — pass it as `?key=`:

```bash theme={null}
curl "https://leakcheck.io/api/v2/query/example@example.com?key=$LEAKCHECK_APIKEY"
```

<Warning>
  Prefer the header: query strings tend to end up in access logs, proxies and
  browser history, so `?key=` is best kept for quick tests and environments
  where setting headers is inconvenient.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://leakcheck.io/api/v2/query/example@example.com" \
    -H "Accept: application/json" \
    -H "X-API-Key: $LEAKCHECK_APIKEY"
  ```

  ```python Python (requests) theme={null}
  import os
  import requests

  response = requests.get(
      "https://leakcheck.io/api/v2/query/example@example.com",
      headers={
          "Accept": "application/json",
          "X-API-Key": os.environ["LEAKCHECK_APIKEY"],
      },
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://leakcheck.io/api/v2/query/example@example.com",
    {
      headers: {
        Accept: "application/json",
        "X-API-Key": process.env.LEAKCHECK_APIKEY,
      },
    }
  );
  console.log(await response.json());
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://leakcheck.io/api/v2/query/example@example.com");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Accept: application/json",
      "X-API-Key: " . getenv("LEAKCHECK_APIKEY"),
  ]);
  $result = json_decode(curl_exec($ch), true);
  curl_close($ch);
  print_r($result);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"io"
  	"net/http"
  	"os"
  )

  func main() {
  	req, _ := http.NewRequest("GET",
  		"https://leakcheck.io/api/v2/query/example@example.com", nil)
  	req.Header.Set("Accept", "application/json")
  	req.Header.Set("X-API-Key", os.Getenv("LEAKCHECK_APIKEY"))

  	resp, err := http.DefaultClient.Do(req)
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	body, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

<Tip>
  Keep the key out of your source code — read it from an environment variable
  (the official Python wrapper picks up `LEAKCHECK_APIKEY` automatically).
</Tip>

Requests without the header are rejected with `401 Missing X-API-Key`, and
requests with a wrong key with `400 Invalid X-API-Key` — see
[Errors](/errors) for the full list.


# Errors & rate limits
Source: https://docs.leakcheck.io/errors

Error responses of the LeakCheck API and the request-rate limits that apply.

## Errors

The API reports failures with a standard HTTP status code and an error
message describing the condition:

| Error                                         | Status code | Notes                                                      |
| --------------------------------------------- | ----------- | ---------------------------------------------------------- |
| Missing X-API-Key header                      | 401         | No API key provided in the request header.                 |
| Invalid X-API-Key                             | 400         | The API key provided is invalid.                           |
| Invalid type                                  | 400         | The `type` parameter is not one of the supported values.   |
| Invalid email                                 | 400         | The email format is incorrect.                             |
| Invalid query                                 | 400         | The query format is invalid.                               |
| Invalid domain                                | 400         | The domain format is invalid.                              |
| Too short query (\< 3 characters)             | 400         | The query must be at least 3 characters long.              |
| Invalid characters in query                   | 400         | The query contains characters that are not allowed.        |
| Too many requests                             | 429         | You have exceeded the rate limit — see below.              |
| Active plan required                          | 403         | A paid plan is required to make this request.              |
| Limit reached                                 | 403         | You have reached your plan's usage quota.                  |
| Could not determine search type automatically | 422         | Auto-detection failed — pass an explicit `type` parameter. |

Handle `429` responses by backing off and retrying; treat `403` as a signal
to check your plan status or remaining quota (the `quota` field of every
successful response tells you how many queries you have left).

## Rate limits

| API        | Limit               | Notes                                              |
| ---------- | ------------------- | -------------------------------------------------- |
| Pro API v2 | 3 requests / second | Applies to any plan; can be increased in settings. |
| Public API | 1 request / second  | Fixed.                                             |

By default, the Pro API is limited to 3 requests per second on any plan. You
can increase this limit in your account settings.


# Overview
Source: https://docs.leakcheck.io/overview

REST API for searching 10B+ leaked records — emails, usernames, phones, domains and info-stealer logs.

The LeakCheck API lets you check whether an identifier — an email address,
username, phone number, domain or password hash — appears in known data
breaches and info-stealer logs.

There are two APIs:

* **Pro API v2** — authenticated with an API key. Returns full breach records
  (including passwords and all leaked fields), supports every search type and
  pagination. Available on paid plans.
* **Public API** — no authentication required. Returns only the list of
  breach sources and the categories of exposed data, never the data itself.
  Free, including commercial use.

## Pro API vs Public API

|                                 | Pro API v2          | Public API |
| ------------------------------- | ------------------- | ---------- |
| Search by e-mail, username      | ✅                   | ✅          |
| Sources display                 | ✅                   | ✅          |
| Passwords display               | ✅                   | ❌          |
| Full data exposure              | ✅                   | ❌          |
| Allowed RPS                     | 3 (upgradeable)     | 1          |
| Search by password, domain name | ✅ (from Enterprise) | ❌          |
| Pricing                         | from \$9.99/mo      | free       |

## Base URLs

```text theme={null}
Pro API v2:  https://leakcheck.io/api/v2
Public API:  https://leakcheck.io/api/public
```

## Quick start

<CodeGroup>
  ```bash Pro API v2 theme={null}
  curl "https://leakcheck.io/api/v2/query/example@example.com" \
    -H "Accept: application/json" \
    -H "X-API-Key: $LEAKCHECK_APIKEY"
  ```

  ```bash Public API theme={null}
  curl "https://leakcheck.io/api/public?check=example@example.com"
  ```

  ```python Python (wrapper) theme={null}
  from leakcheck import LeakCheckAPI_v2

  api = LeakCheckAPI_v2(api_key="your_api_key_here")
  result = api.lookup(query="example@example.com")
  print(result)
  ```
</CodeGroup>

<CardGroup>
  <Card title="Pro API v2 lookup" icon="magnifying-glass" href="/pro-api/lookup">
    The main query endpoint: request, response and pagination.
  </Card>

  <Card title="Search types" icon="filter" href="/pro-api/search-types">
    Everything you can search by, from emails to info-stealer origins.
  </Card>

  <Card title="Public API" icon="globe" href="/public-api/lookup">
    Free breach-source lookups without an API key.
  </Card>

  <Card title="Python wrapper & CLI" icon="python" href="/tools/python-wrapper">
    Official `leakcheck` package on PyPI, with a CLI tool included.
  </Card>
</CardGroup>

## Commercial usage

You are free to use the Public API for commercial purposes — the only
requirement is a "Powered by LeakCheck" link on your website (see
[Public API terms](/public-api/lookup#terms-and-conditions)).

If you wish to use the Pro API commercially, please contact our support team
at [the@leakcheck.net](mailto:the@leakcheck.net) and describe your project.


# Lookup
Source: https://docs.leakcheck.io/pro-api/lookup

Query the Pro API v2 for full breach records by email, username, phone, domain and more.

The Pro API v2 has a single lookup endpoint:

```text theme={null}
GET https://leakcheck.io/api/v2/query/{query}
```

Requires an [API key](/authentication) — in the `X-API-Key` header or as a
`?key=` query parameter.

## Parameters

<ParamField type="string">
  The value to search for — an email address, username, phone number, hash,
  domain, etc. Minimum 3 characters.
</ParamField>

<ParamField type="string">
  Your API key, as an alternative to the `X-API-Key` header.
</ParamField>

<ParamField type="string">
  Search type. When omitted, the type is detected automatically (works for
  email, username, phone number and hash). Other types — such as `domain`,
  `keyword`, `origin` or `password` — must be set explicitly. See
  [Search types](/pro-api/search-types) for the full list.
</ParamField>

<ParamField type="integer">
  Maximum number of rows to return. Cannot exceed 1000.
</ParamField>

<ParamField type="integer">
  Number of rows to skip, for pagination. Cannot exceed 2500.
</ParamField>

## Sample request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://leakcheck.io/api/v2/query/example@example.com?limit=100" \
    -H "Accept: application/json" \
    -H "X-API-Key: $LEAKCHECK_APIKEY"
  ```

  ```python Python (requests) theme={null}
  import os
  import requests

  response = requests.get(
      "https://leakcheck.io/api/v2/query/example@example.com",
      params={"type": "email", "limit": 100, "offset": 0},
      headers={
          "Accept": "application/json",
          "X-API-Key": os.environ["LEAKCHECK_APIKEY"],
      },
  )
  data = response.json()
  print(f"found {data['found']} rows, {data['quota']} queries left")
  ```

  ```python Python (wrapper) theme={null}
  from leakcheck import LeakCheckAPI_v2

  # Reads LEAKCHECK_APIKEY from the environment if api_key is omitted
  api = LeakCheckAPI_v2(api_key="your_api_key_here")

  result = api.lookup(query="example@example.com", query_type="email", limit=100)
  print(result)
  ```

  ```javascript Node.js theme={null}
  const query = encodeURIComponent("example@example.com");
  const response = await fetch(
    `https://leakcheck.io/api/v2/query/${query}?limit=100`,
    {
      headers: {
        Accept: "application/json",
        "X-API-Key": process.env.LEAKCHECK_APIKEY,
      },
    }
  );
  const data = await response.json();
  console.log(`found ${data.found} rows, ${data.quota} queries left`);
  ```

  ```php PHP theme={null}
  <?php
  $query = urlencode("example@example.com");
  $ch = curl_init("https://leakcheck.io/api/v2/query/{$query}?limit=100");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Accept: application/json",
      "X-API-Key: " . getenv("LEAKCHECK_APIKEY"),
  ]);
  $data = json_decode(curl_exec($ch), true);
  curl_close($ch);
  echo "found {$data['found']} rows, {$data['quota']} queries left\n";
  ```

  ```go Go theme={null}
  package main

  import (
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"net/url"
  	"os"
  )

  func main() {
  	query := url.PathEscape("example@example.com")
  	req, _ := http.NewRequest("GET",
  		"https://leakcheck.io/api/v2/query/"+query+"?limit=100", nil)
  	req.Header.Set("Accept", "application/json")
  	req.Header.Set("X-API-Key", os.Getenv("LEAKCHECK_APIKEY"))

  	resp, err := http.DefaultClient.Do(req)
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	var data struct {
  		Success bool             `json:"success"`
  		Found   int              `json:"found"`
  		Quota   int              `json:"quota"`
  		Result  []map[string]any `json:"result"`
  	}
  	json.NewDecoder(resp.Body).Decode(&data)
  	fmt.Printf("found %d rows, %d queries left\n", data.Found, data.Quota)
  }
  ```
</CodeGroup>

## Sample response

```json theme={null}
{
    "success": true,
    "found": 1,
    "quota": 400,
    "result": [
        {
            "email": "example@example.com",
            "source": {
                "name": "BreachedWebsite.net",
                "breach_date": "2019-07",
                "unverified": 0,
                "passwordless": 0,
                "compilation": 0
            },
            "first_name": "Example",
            "last_name": "Example",
            "username": "leakcheck",
            "fields": ["first_name", "last_name", "username"]
        }
    ]
}
```

Or, if nothing was found:

```json theme={null}
{
    "success": true,
    "found": 0,
    "quota": 400,
    "result": []
}
```

## Response fields

<ResponseField name="found" type="integer">
  Number of rows found and returned.
</ResponseField>

<ResponseField name="quota" type="integer">
  The number of queries remaining on your account.
</ResponseField>

<ResponseField name="result" type="array">
  Array of associative arrays containing the results of the search. Each row
  carries a `source` object (breach name, `breach_date`, and `unverified` /
  `passwordless` / `compilation` flags) plus a `fields` list naming the data
  present in that row. Info-stealer log rows additionally carry a `collected`
  string (an exact `YYYY-MM-DD`, or `"April 2024 or earlier"` for older
  bulk-imported records) since they have no source `breach_date`.
</ResponseField>

<Note>
  Rows can contain various data from breached databases. The list includes but
  is not limited to: `username`, `password`, `first_name`, `last_name`, `dob`,
  `address`, `zip`, `phone`, `name`.
</Note>


# Migrate from v1
Source: https://docs.leakcheck.io/pro-api/migrate-from-v1

What changed between the legacy API v1 and the Pro API v2.

In v2 we have combined all the data together, so there are no search types
like `pass_login` or `domain_email` — just use `password` or `domain`.

What else is different:

1. 🚀 **1.5x faster** for regular queries and **3x** for domain queries —
   expect almost no latency.
2. 📄 Filled with data compiled from all leaked databases.
3. 🦠 It's now possible to search the data from info-stealer logs by their
   origin (`type=origin`).
4. 🔍 REST-compliant and simplified search — one endpoint,
   `GET /api/v2/query/{query}`.
5. 🔓 **No more IP linking.** Hooray!

<Note>
  Authentication also moved to the `X-API-Key` header — see
  [Authentication](/authentication).
</Note>


# Search types
Source: https://docs.leakcheck.io/pro-api/search-types

Everything you can search by with the Pro API v2, and when a type must be set explicitly.

By default, the type of search is determined automatically. If you prefer —
or when auto-detection is not possible — specify it explicitly with the
`?type=` query parameter.

| Type       | Sample                                                                                         | Notes                                                                                                                     |
| ---------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `auto`     | [example@example.com](mailto:example@example.com), example, 12345678, 31c5543c1734d25c7206f5fd | Only email, username, phone number and hash can be detected automatically. For other data you should set type explicitly. |
| `email`    | [example@example.com](mailto:example@example.com)                                              |                                                                                                                           |
| `domain`   | gmail.com                                                                                      |                                                                                                                           |
| `keyword`  | example                                                                                        |                                                                                                                           |
| `username` | example                                                                                        |                                                                                                                           |
| `phone`    | 12063428631                                                                                    |                                                                                                                           |
| `hash`     | 31c5543c1734d25c7206f5fd                                                                       | SHA256 hash of lower-cased email. You can also truncate it to 24 characters.                                              |
| `phash`    | 31c5543c1734d25c7206f5fd                                                                       | SHA256 hash of password. You can also truncate it to 24 characters. **Enterprise only.**                                  |
| `origin`   | example.com                                                                                    | Search info-stealer logs by the site the credentials belong to. **Enterprise only.**                                      |
| `password` | example                                                                                        | **Enterprise only.**                                                                                                      |

## Pagination

You can also specify `limit` and `offset` query parameters. `limit` can't be
bigger than **1000** and `offset` than **2500**.

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  # Explicit domain search
  curl "https://leakcheck.io/api/v2/query/gmail.com?type=domain&limit=500" \
    -H "Accept: application/json" \
    -H "X-API-Key: $LEAKCHECK_APIKEY"
  ```

  ```python Python (wrapper) theme={null}
  from leakcheck import LeakCheckAPI_v2

  api = LeakCheckAPI_v2(api_key="your_api_key_here")

  # Auto-detect type
  result = api.lookup(query="example@example.com")

  # Lookup by email
  result = api.lookup(query="example@example.com", query_type="email")

  # Lookup by domain
  result = api.lookup(query="gmail.com", query_type="domain")

  # Lookup by phone
  result = api.lookup(query="12063428631", query_type="phone")

  # Lookup by SHA256 hash
  result = api.lookup(query="31c5543c1734d25c7206f5fd", query_type="hash")
  ```

  ```javascript Node.js theme={null}
  const lookup = async (query, type) => {
    const params = new URLSearchParams(type ? { type } : {});
    const response = await fetch(
      `https://leakcheck.io/api/v2/query/${encodeURIComponent(query)}?${params}`,
      { headers: { "X-API-Key": process.env.LEAKCHECK_APIKEY } }
    );
    return response.json();
  };

  await lookup("example@example.com");          // auto-detected
  await lookup("gmail.com", "domain");          // explicit type
  await lookup("12063428631", "phone");
  ```
</CodeGroup>

<Tip>
  Hash searches let you check an email without sending it in plain text:
  compute the SHA-256 of the lower-cased address and query with `type=hash`.
</Tip>


# Lookup
Source: https://docs.leakcheck.io/public-api/lookup

Free breach-source lookups by email, email hash or username — no API key required.

The Public API tells you **where** an identifier was leaked and **what kinds
of data** were exposed, without revealing the data itself. It requires no
authentication and is free to use, including for commercial projects.

```text theme={null}
GET https://leakcheck.io/api/public?check={query}
```

<Info>
  The search type is detected automatically.
</Info>

## Accepted data

| Type           | Sample                                            | Notes                              |
| -------------- | ------------------------------------------------- | ---------------------------------- |
| E-mail         | [example@example.com](mailto:example@example.com) |                                    |
| E-mail by hash | 31c5543c1734d25c7206f5fd                          | SHA256, truncated to 24 characters |
| Username       | example                                           | min. 3 characters                  |

## Sample request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://leakcheck.io/api/public?check=example@example.com"
  ```

  ```python Python (requests) theme={null}
  import requests

  response = requests.get(
      "https://leakcheck.io/api/public",
      params={"check": "example@example.com"},
  )
  data = response.json()
  if data["found"]:
      for source in data["sources"]:
          print(f"{source['name']} ({source['date']})")
  ```

  ```python Python (wrapper) theme={null}
  from leakcheck import LeakCheckAPI_Public

  public_api = LeakCheckAPI_Public()
  result = public_api.lookup(query="example@example.com")
  print(result)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://leakcheck.io/api/public?check=" +
      encodeURIComponent("example@example.com")
  );
  const data = await response.json();
  if (data.found) {
    for (const source of data.sources) {
      console.log(`${source.name} (${source.date})`);
    }
  }
  ```

  ```php PHP theme={null}
  <?php
  $check = urlencode("example@example.com");
  $data = json_decode(
      file_get_contents("https://leakcheck.io/api/public?check={$check}"),
      true
  );
  foreach ($data["sources"] ?? [] as $source) {
      echo "{$source['name']} ({$source['date']})\n";
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"net/url"
  )

  func main() {
  	resp, err := http.Get(
  		"https://leakcheck.io/api/public?check=" +
  			url.QueryEscape("example@example.com"))
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	var data struct {
  		Success bool     `json:"success"`
  		Found   int      `json:"found"`
  		Fields  []string `json:"fields"`
  		Sources []struct {
  			Name string `json:"name"`
  			Date string `json:"date"`
  		} `json:"sources"`
  	}
  	json.NewDecoder(resp.Body).Decode(&data)
  	for _, s := range data.Sources {
  		fmt.Printf("%s (%s)\n", s.Name, s.Date)
  	}
  }
  ```
</CodeGroup>

## Sample response

```json theme={null}
{
    "success": true,
    "found": 3,
    "fields": ["username", "first_name", "address"],
    "sources": [
        {
            "name": "Evony.com",
            "date": "2016-07"
        },
        {
            "name": "I-Dressup.com",
            "date": "2016-08"
        },
        {
            "name": "Zynga.com",
            "date": "2019-09"
        }
    ]
}
```

## Response fields

<ResponseField name="found" type="integer">
  Number of breach records that match the query.
</ResponseField>

<ResponseField name="fields" type="array">
  Categories of data exposed across the matching breaches (e.g. `username`,
  `first_name`, `address`). The values themselves are never returned — use
  the [Pro API](/pro-api/lookup) for full records.
</ResponseField>

<ResponseField name="sources" type="array">
  The breaches the identifier appears in, each with a `name` and a `date`
  (`YYYY-MM`).
</ResponseField>

## Rate limit

The Public API is limited to **1 request per second**.

## Terms and conditions

The one and only thing required is to add a small **"Powered by LeakCheck"**
link if you use the API on your website. The text can vary but should
include the service name. You can also use affiliate links.


# CLI tool
Source: https://docs.leakcheck.io/tools/cli

Query the LeakCheck API straight from your terminal with the leakcheck command.

The [`leakcheck` Python package](/tools/python-wrapper) includes a
command-line interface for querying the API directly from your terminal.

## Installation

```bash theme={null}
pip install leakcheck
```

## Usage

```bash theme={null}
leakcheck "example@example.com" --type email --limit 50 --api-key your_api_key_here
```

More examples:

```bash theme={null}
# Auto-detect the query type, key from LEAKCHECK_APIKEY
export LEAKCHECK_APIKEY=your_api_key_here
leakcheck "example@example.com"

# Use the free Public API instead of the authenticated one
leakcheck "example@example.com" --public

# Domain search with prettified JSON output
leakcheck "gmail.com" --type domain --pretty

# Route the request through a proxy
leakcheck "example" --type username --proxy socks5://127.0.0.1:9050
```

## Help menu

```text theme={null}
usage: leakcheck [-h] [--type TYPE] [--limit LIMIT] [--offset OFFSET] [--public] [--api-key API_KEY] [--proxy PROXY] [--pretty] query

LeakCheck CLI Tool

positional arguments:
  query                 The value to search for (email, username, etc.)

options:
  -h, --help            show this help message and exit
  --type TYPE, -t TYPE  Type of query (email, username, etc.). Will be auto-detected if not provided.
  --limit LIMIT, -l LIMIT
                        Limit the number of results (max 1000, default 100)
  --offset OFFSET, -o OFFSET
                        Offset the results (max 2500, default 0)
  --public, -p          Use the public API instead of the authenticated API.
  --api-key API_KEY     API key to authenticate with the LeakCheck service. If not provided, will attempt to read from environment variable.
  --proxy PROXY         Optional proxy to use for the requests (HTTP, HTTPS, SOCKS5 supported). If not provided, will attempt to read from environment variable.
  --pretty              Display prettified JSON output instead of a table.
```


# Python wrapper
Source: https://docs.leakcheck.io/tools/python-wrapper

Official Python package for the LeakCheck API — supports both the Pro API v2 and the Public API.

The official Python wrapper lets you interact with the LeakCheck API from
your code. It supports both the private (authenticated) **Pro API v2** and
the public (unauthenticated) API, and ships with a [CLI tool](/tools/cli).

Source code: [github.com/LeakCheck/leakcheck-api](https://github.com/LeakCheck/leakcheck-api) · MIT license.

## Features

* Lookup email addresses, usernames, and other identifiers against leaked databases.
* Supports both the **Pro API v2** (authenticated via API key) and the **Public API**.
* HTTP/SOCKS proxy support.
* Customizable request limits and offsets for paginated queries.

## Installation

```bash theme={null}
pip install leakcheck
```

## Pro API v2 — `LeakCheckAPI_v2`

To use the Pro API, you need an API key from LeakCheck. You can pass the key
directly or set it via an environment variable.

```python theme={null}
from leakcheck import LeakCheckAPI_v2

# Initialize with API key (or set LEAKCHECK_APIKEY in environment variables)
api = LeakCheckAPI_v2(api_key="your_api_key_here")

# Perform a lookup
result = api.lookup(query="example@example.com", query_type="email", limit=100)

print(result)
```

### Environment variables

| Variable           | Purpose                                                                |
| ------------------ | ---------------------------------------------------------------------- |
| `LEAKCHECK_APIKEY` | Your API key for authentication (must be at least 40 characters long). |
| `LEAKCHECK_PROXY`  | Optional, to route your requests through a proxy.                      |

### Parameters for `lookup()`

<ParamField type="string">
  The identifier to look up (email, username, etc.).
</ParamField>

<ParamField type="string">
  The type of query (e.g. `email`, `username`). Auto-detected if not
  provided — see [Search types](/pro-api/search-types).
</ParamField>

<ParamField type="integer">
  Limit the number of results (maximum 1000).
</ParamField>

<ParamField type="integer">
  Offset for the results (maximum 2500).
</ParamField>

### Error handling

`lookup()` raises a `ValueError` when the API returns an error, which makes
failures easy to catch and debug:

```python theme={null}
try:
    result = api.lookup(query="example@example.com", query_type="email", limit=100)
    print(result)
except ValueError as e:
    print(f"An error occurred: {str(e)}")
```

* If the API key is invalid or not provided, an error is raised.
* The method validates the `limit` and `offset` parameters.
* Network and request exceptions are handled as well.

The error messages match the [API error table](/errors).

## Public API — `LeakCheckAPI_Public`

The Public API does not require authentication but offers limited access —
use it for simple email or username source checks:

```python theme={null}
from leakcheck import LeakCheckAPI_Public

# Initialize without an API key
public_api = LeakCheckAPI_Public()

# Perform a public lookup
result = public_api.lookup(query="example@example.com")

print(result)
```

`lookup()` takes a single `query` — an email, an email hash, or a username.

## Proxy support

Both wrappers support proxy configurations (HTTP, HTTPS, SOCKS5). Set the
proxy with `set_proxy()` or via the `LEAKCHECK_PROXY` environment variable:

```python theme={null}
# Set proxy for the Pro API
api.set_proxy("http://proxy.example.com:8080")

# Set proxy for the Public API
public_api.set_proxy("http://proxy.example.com:8080")
```