> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osintcat.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Breach Lookup

> Search breach and leak indexes for an e-mail, username, IP or password

Searches the breach indexes for a value and returns every matching record in one request. The search is case-insensitive, except for passwords and hashes.

This endpoint answers with the fast sources. The deep search, which covers more sources and can take a minute or longer, runs as a job: see [Breach Search Job](https://docs.osintcat.net/api-reference/endpoint/breach-search.md).

> [!NOTE]
>
> Records for the same query may come from a cache for up to 72 hours. Every request is counted and charged, whether or not its records came from the cache.

## Parameters

**query** `string` *required*

What to search for: an e-mail address, username, domain, IP address, name, phone number, hash or password.

**type** `string`

What `query` is: `email`, `username`, `password`, `name`, `domain`, `ip`, `hash` or `phone`. Detected from the query when left out; set it for a name or a password, which can't be told apart from a username.

## Headers

**X-API-KEY** `string` *required*

Your API key.

## Usage

Available on paid plans and pay as you go. Counts as one lookup against your plan's daily allowance (Max: unlimited). When the allowance is used up, the lookup can continue at a per-lookup price charged to your balance (the module's page in the dashboard shows the price). The price applies even when the lookup finds nothing; a lookup that fails because of an error on our side is not charged.

## Example request

```bash cURL theme={null}
curl "https://www.osintcat.net/api/breach?query=user%40example.com" \
     -H "X-API-KEY: YOUR_API_KEY"
```

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

url = "https://www.osintcat.net/api/breach"
params = {"query": "user@example.com"}
headers = {"X-API-KEY": "YOUR_API_KEY"}

response = requests.get(url, params=params, headers=headers, timeout=60)
print(response.status_code, response.json())
```

```javascript JS & TS theme={null}
const response = await fetch("https://www.osintcat.net/api/breach?query=user%40example.com", {
  headers: { "X-API-KEY": "YOUR_API_KEY" },
});
console.log(response.status, await response.json());
```

```php PHP theme={null}
<?php
$curl = curl_init("https://www.osintcat.net/api/breach?query=user%40example.com");
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-KEY: YOUR_API_KEY"],
]);
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
echo $status . " " . $response;
```

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

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

func main() {
    req, _ := http.NewRequest("GET", "https://www.osintcat.net/api/breach?query=user%40example.com", nil)
    req.Header.Set("X-API-KEY", "YOUR_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(resp.StatusCode, string(body))
}
```

## SDK example

The same request with the [official SDKs](https://docs.osintcat.net/sdks.md). Each one reads your key from `OSINTCAT_API_KEY`.

```typescript JS & TS theme={null}
import { OsintCatClient } from "osintcat";

const client = new OsintCatClient(); // reads OSINTCAT_API_KEY

const result = await client.breach.search({
    query: "user@example.com"
});
console.log(result);
```

```python Python theme={null}
from osintcat import OsintCat

client = OsintCat()  # reads OSINTCAT_API_KEY

result = client.breach.search(
    query="user@example.com",
)
print(result)
```

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

import (
	"context"
	"fmt"

	osintcat "github.com/OsintCatHQ/osintcat-go"
	osintcatclient "github.com/OsintCatHQ/osintcat-go/client"
)

func main() {
	client := osintcatclient.NewClient() // reads OSINTCAT_API_KEY
	request := &osintcat.SearchBreachRequest{
		Query: "user@example.com",
	}
	result, err := client.Breach.Search(context.Background(), request)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", result)
}
```

```php PHP theme={null}
<?php
require __DIR__ . '/vendor/autoload.php';

use OsintCat\OsintCatClient;
use OsintCat\Breach\Requests\SearchBreachRequest;

$client = new OsintCatClient(); // reads OSINTCAT_API_KEY

$result = $client->breach->search(
    new SearchBreachRequest([
        'query' => 'user@example.com',
    ]),
);
echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL;
```

## Response

**api** `string`

Always `OsintCat`.

**elapsed\_ms** `number`

Time the search took, in milliseconds.

**timestamp** `string`

When the search ran (UTC), e.g. `Oct 6th 09:41`.

**query\_type** `string`

The type the query was searched as (the `type` you sent, or the detected one).

**results\_count** `number`

Number of records in `breach_data`.

**breach\_data** `array`

Matching records. The fields of a record depend on the breach it comes from (for example `email`, `username`, `password`, `hash`, `ip`, `name`, `phone`); `source_db` names the breach the record was found in, when it is known.

**password\_seen** `number`

Only for `type=password`: how often the password appears in known breaches.

**sources** `object`

One entry per source that searched, by id (`b1`, `b2`, ...): `status` (`completed` or `error`), `count`, and for an error a short `error` message. A source that failed doesn't fail the request.

**deep\_search** `string`

The endpoint for the deep search job, `/api/breach/search`.

**\_meta** `object`

Your usage after this request.

**properties**

**plan** `string`

Plan id.

**lookups\_left** `number | string`

Lookups left today, `unlimited` on Max, or `charging` when the allowance is used up and the lookup was charged to your balance.

```json 200 theme={null}
{
  "api": "OsintCat",
  "elapsed_ms": 1843.27,
  "timestamp": "Oct 6th 09:41",
  "query_type": "email",
  "results_count": 1,
  "breach_data": [
    {
      "email": "user@example.com",
      "username": "user123",
      "password": "hunter2",
      "source_db": "EXAMPLE_COM_2019"
    }
  ],
  "sources": {
    "b1": { "status": "completed", "count": 0 },
    "b2": { "status": "completed", "count": 1 }
  },
  "deep_search": "/api/breach/search",
  "_meta": {
    "plan": "investigator",
    "lookups_left": 741
  }
}
```

## Errors

See [Errors](https://docs.osintcat.net/api-reference/introduction.md#errors) for the responses every endpoint can return.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.