# OsintCat API > This file is very large and may be truncated. For an index of this content, please refer to https://docs.osintcat.net/llms.txt instead. # Breach Lookup Source: https://docs.osintcat.net/api-reference/endpoint/breach GET https://www.osintcat.net/api/breach 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](/api-reference/endpoint/breach-search). > [!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} 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](/sdks). 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} 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](/api-reference/introduction#errors) for the responses every endpoint can return. # Breach Search Job Source: https://docs.osintcat.net/api-reference/endpoint/breach-search POST https://www.osintcat.net/api/breach/search The deep breach search: every source, run as a job you poll Starts a breach search across every source, including the deep search, which [Breach Lookup](/api-reference/endpoint/breach) leaves out because it can take a minute or longer. The answer comes at once with a job `id`; poll `GET /api/breach/search/{id}` until `status` is `completed`. Records appear while the sources answer. > [!NOTE] > > Records for the same query may come from a cache for up to 72 hours. Every search is counted and charged; polling a job is free. ## Body **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. **deep** `boolean` (default: true) `false` leaves the deep search out (then a `phone` search has no source and is refused). ## 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 search can continue at a per-lookup price charged to your balance. The price applies even when the search finds nothing; a search where every source fails is not charged. ## Start a search ```bash cURL theme={null} curl -X POST "https://www.osintcat.net/api/breach/search" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "user@example.com"}' ``` ```python Python theme={null} import time import requests headers = {"X-API-KEY": "YOUR_API_KEY"} job = requests.post("https://www.osintcat.net/api/breach/search", json={"query": "user@example.com"}, headers=headers, timeout=30).json() while True: state = requests.get("https://www.osintcat.net" + job["poll"], headers=headers, timeout=30).json() if state["status"] == "completed": break time.sleep(3) print(state["results_count"], state["breach_data"][:3]) ``` ```javascript JS & TS theme={null} const headers = { "X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json" }; const job = await (await fetch("https://www.osintcat.net/api/breach/search", { method: "POST", headers, body: JSON.stringify({ query: "user@example.com" }), })).json(); let state; do { await new Promise((r) => setTimeout(r, 3000)); state = await (await fetch("https://www.osintcat.net" + job.poll, { headers })).json(); } while (state.status !== "completed"); console.log(state.results_count, state.breach_data.slice(0, 3)); ``` The answer, HTTP 202: **id** `string` The job id. **status** `string` `running`. **query_type** `string` The type the query is searched as. **sources** `array` The ids of the sources searching (`b1`, `b2`, ...). **poll** `string` The path to poll, `/api/breach/search/{id}`. **\_meta** `object` Your usage after this request (`plan`, `lookups_left`), as on [Breach Lookup](/api-reference/endpoint/breach). ## Poll a search `GET https://www.osintcat.net/api/breach/search/{id}` with the same `X-API-KEY`. Only the key that started a job can read it; a job is kept for 30 minutes. Polling is free; a few seconds between polls is plenty. **id** `string` The job id. **status** `string` `running` while sources are still searching, then `completed`. **query_type** `string` The type the query is searched as. **results_count** `number` Number of records in `breach_data` so far. **breach_data** `array` Matching records from every source that has answered; `source_db` names the breach 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 by id: `status` (`pending`, `completed` or `error`), `count`, and for an error a short `error` message. ```json 202 theme={null} { "id": "0f0e0d0c-0000-4000-8000-000000000001", "status": "running", "query_type": "email", "sources": ["b1", "b2", "b3"], "poll": "/api/breach/search/0f0e0d0c-0000-4000-8000-000000000001", "_meta": { "plan": "investigator", "lookups_left": 741 } } ``` ```json 200 theme={null} { "id": "0f0e0d0c-0000-4000-8000-000000000001", "status": "completed", "query_type": "email", "results_count": 1, "breach_data": [ { "email": "user@example.com", "password": "hunter2", "source_db": "EXAMPLE_COM_2019" } ], "sources": { "b1": { "status": "completed", "count": 0 }, "b2": { "status": "completed", "count": 1 }, "b3": { "status": "completed", "count": 0 } } } ``` ## Errors `403` with `upgrade_required` on the free plan; `400` with `invalid_query` or `invalid_type` for a missing query or an unknown type; `404` for a job that doesn't exist, expired, or was started by another key. See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Chess.com Lookup Source: https://docs.osintcat.net/api-reference/endpoint/chess GET https://www.osintcat.net/api/chess-osint Chess.com profile, ratings, clubs and leaked records Returns the Chess.com profile of a player (ratings, clubs) and any records about the account found in the Chess.com leak. ## Parameters **query** `string` *required* A Chess.com username or an e-mail address. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/chess-osint?query=hikaru" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/chess-osint" params = {"query": "hikaru"} 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/chess-osint?query=hikaru", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/chess-osint?query=hikaru", 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](/sdks). 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.chess.lookup({ query: "hikaru" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.chess.lookup( query="hikaru", ) 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.LookupChessRequest{ Query: "hikaru", } result, err := client.Chess.Lookup(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} chess->lookup( new LookupChessRequest([ 'query' => 'hikaru', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **success** `boolean` `true` when the lookup ran. **found** `boolean` Whether anything was found. **query** `string` The query. **resolved_username** `string` The username the lookup settled on. **live_profile** `object` The public profile (name, country, joined, last online, followers ...), or `null`. **live_stats** `object` Ratings: `rapid`, `blitz`, `bullet`, `fide` (each `null` when unrated). **live_clubs** `array` Up to 10 clubs. **leak_records** `array` Records from the Chess.com leak. **leak_count** `number` Number of leak records. ```json 200 theme={null} { "success": true, "found": true, "query": "hikaru", "resolved_username": "hikaru", "live_profile": { "username": "hikaru", "country": "US", "joined": 1389043258 }, "live_stats": { "rapid": 2850, "blitz": 3300, "bullet": 3200, "fide": 2800 }, "live_clubs": [], "leak_records": [], "leak_count": 0 } ``` ## Errors See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Database Search Source: https://docs.osintcat.net/api-reference/endpoint/database-search GET https://www.osintcat.net/api/database-search Search stealer-log and combo-list collections by e-mail or domain Searches stealer-log and combo-list collections for an e-mail address or a domain. ## Parameters **query** `string` *required* The e-mail address or domain. **type** `string` `email` or `domain`. Detected from `query` when left out. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/database-search?query=user%40example.com&type=email" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/database-search" params = {"query": "user@example.com", "type": "email"} 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/database-search?query=user%40example.com&type=email", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/database-search?query=user%40example.com&type=email", 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](/sdks). 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.databaseSearch({ query: "user@example.com" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.breach.database_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.DatabaseSearchBreachRequest{ Query: "user@example.com", } result, err := client.Breach.DatabaseSearch(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} breach->databaseSearch( new DatabaseSearchBreachRequest([ 'query' => 'user@example.com', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **results** `array` Matching entries (typically a URL, login and password, and when it was collected). **results_count** `number` Number of entries. **query** `string` The query searched for. **type** `string` `email` or `domain`. **execution_time** `string` Time the search took. **status** `string` `success`. ```json 200 theme={null} { "results": [ { "url": "https://accounts.example.org/login", "login": "user@example.com", "password": "hunter2", "date": "2025-11-02" } ], "results_count": 1, "query": "user@example.com", "type": "email", "execution_time": "0.84s", "status": "success" } ``` ## Errors | Status | Error | When | | - | - | - | | 424 | `Upstream error` | The search backend answered with an error. Not charged. | | 424 | `timeout error` | The search backend did not answer in time. Not charged. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Discord Lookup Source: https://docs.osintcat.net/api-reference/endpoint/discord GET https://www.osintcat.net/api/discord Search leaked Discord account records Searches leaked Discord account records. The query matches partially on the user ID, username, e-mail, phone, IP address, Steam ID and license. Up to 100 records are returned. > [!NOTE] > > While the Discord index is under maintenance the endpoint answers `503` with an empty `results` list; nothing is charged. ## Parameters **query** `string` *required* A Discord user ID, username, e-mail, phone number, IP address, Steam ID or license. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/discord?query=80351110224678912" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/discord" params = {"query": "80351110224678912"} 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/discord?query=80351110224678912", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/discord?query=80351110224678912", 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)) } ``` ## Response **query** `string` The query searched for. **count** `number` Number of records. **results** `array` Matching records. **properties** **user_id** `string` Discord user ID. **username** `string` Username. **discriminator** `string` Legacy discriminator, if any. **email** `string` E-mail. **phone** `string` Phone number. **password** `string` Password, if the record has one. **ip** `string` IP address. **token** `string` Token, if the record has one. **steam** `string` Linked Steam ID. **license** `string` Game license identifier. **source** `string` Collection the record came from. **added_at** `string` When the record was added. ```json 200 theme={null} { "query": "80351110224678912", "count": 1, "results": [ { "user_id": "80351110224678912", "username": "example", "discriminator": "0", "email": "user@example.com", "phone": null, "password": null, "ip": "203.0.113.7", "token": null, "steam": null, "license": null, "source": "example-2024", "added_at": "2025-02-11 08:00:00" } ] } ``` ## Errors | Status | Error | When | | - | - | - | | 424 | `Discord search service temporarily unavailable` | The search failed. | | 503 | `(maintenance)` | The Discord index is under maintenance. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Discord to Roblox Source: https://docs.osintcat.net/api-reference/endpoint/discord-to-roblox GET https://www.osintcat.net/api/discord-to-roblox Roblox accounts linked to a Discord account > [!WARNING] > > This lookup is currently unavailable; requests are refused with `403 ACCESS_DENIED`. Finds Roblox accounts linked to a Discord user ID. ## Parameters **query** `string` *required* A Discord user ID. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage Counts as one lookup against your plan's daily allowance (Max: unlimited). When the allowance is used up, requests are refused with `429 LIMIT_REACHED` until it resets at 00:00 UTC. ## Example request ```bash cURL theme={null} curl "https://www.osintcat.net/api/discord-to-roblox?query=80351110224678912" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/discord-to-roblox" params = {"query": "80351110224678912"} 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/discord-to-roblox?query=80351110224678912", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/discord-to-roblox?query=80351110224678912", 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)) } ``` ## Response ## Errors See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # DNS Resolver Source: https://docs.osintcat.net/api-reference/endpoint/dns-resolver GET https://www.osintcat.net/api/dns-resolver Resolve hostnames to IP addresses Resolves one or more hostnames to their IP addresses. ## Parameters **query** `string` *required* A hostname, or several separated by commas. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/dns-resolver?query=example.com%2Cosintcat.net" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/dns-resolver" params = {"query": "example.com,osintcat.net"} 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/dns-resolver?query=example.com%2Cosintcat.net", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/dns-resolver?query=example.com%2Cosintcat.net", 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](/sdks). 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.dns.resolve({ query: "example.com,osintcat.net" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.dns.resolve( query="example.com,osintcat.net", ) 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.ResolveDNSRequest{ Query: "example.com,osintcat.net", } result, err := client.DNS.Resolve(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} dns->resolve( new ResolveDnsRequest([ 'query' => 'example.com,osintcat.net', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response An object mapping each hostname to its IP address (`null` when it does not resolve). ```json 200 theme={null} { "example.com": "93.184.215.14", "osintcat.net": "104.21.32.1" } ``` ## Errors See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Email Footprint Source: https://docs.osintcat.net/api-reference/endpoint/email-footprint GET https://www.osintcat.net/api/footprint/create-task Discover platform registrations for an email address across 100+ services > [!WARNING] > > Footprint scans are currently unavailable; requests are refused with `403 ACCESS_DENIED`. The Email Footprint API checks whether a specific email address is registered across social media, shopping, and professional platforms. It returns a summary of stats and a per-platform breakdown including secondary metadata like usernames or account status where available. The lookup backend is load-balanced, so footprint scans run as **asynchronous tasks**: 1. **Create a task** with `GET /api/footprint/create-task` (this is where one lookup is charged). You receive a `task_id`. 2. **Poll the task** with `GET /api/footprint/get-task?id=` until `status` is no longer a running state. Polling is free. > [!NOTE] > > Email and username footprints share the same task endpoints — only the `type` parameter differs (`email` vs `username`). *** ## Step 1 — Create Task ```bash theme={null} GET https://www.osintcat.net/api/footprint/create-task ``` **query** `string` *required* The email address to scan (e.g., `user@gmail.com`) **type** `string` (default: email) The footprint type. Use `email` for this endpoint. **X-API-KEY** `string` *required* Your API key > [!WARNING] > > Creating a task consumes exactly **one lookup** from your daily quota. Polling `get-task` does not. **Response Body** **task_id** `string` The identifier used to poll for results. **status** `string` The initial task status (e.g., `running`, `queued`, `pending`). **\_meta** `object` **properties** **plan** `string` Your current plan. **lookups_left** `string` Remaining lookups for the day (`unlimited` on the Max plan). ```json theme={null} { "task_id": "f3c8a1e2-9b44-4d51-bd0a-1c2e3f4a5b6c", "status": "running", "_meta": { "plan": "researcher", "lookups_left": 4821 } } ``` *** ## Step 2 — Poll Task ```bash theme={null} GET https://www.osintcat.net/api/footprint/get-task ``` **id** `string` *required* The `task_id` returned by `create-task`. **X-API-KEY** `string` *required* Your API key Poll roughly once per second until `status` is no longer one of the running states (`running`, `queued`, `pending`, `processing`, `started`). A scan typically completes within a few seconds and is capped at \~3 minutes. **Response Body** **status** `string` Current task status. While running it is one of `running`, `queued`, `pending`, `processing`, `started`. Any other value (e.g., `done`, `finished`) means the scan is complete. **stats** `object` Live progress / summary counters (populated as the scan runs). **properties** **checked** `number` Number of platforms checked so far. **total_modules** `number` Total number of platforms in the scan. **found** `number` Number of platforms where the email was found. **elapsed** `string` Elapsed scan time. **results** `array` List of platform results (grows as the scan progresses). **item properties** **domain** `string` Platform domain (e.g., `github.com`) **taken** `boolean` True if the email is registered on this platform **ExtraData** `object` Metadata retrieved from the platform (usernames, IDs, status, etc.) *** ## Example ```bash cURL theme={null} # 1. Create the task curl "https://www.osintcat.net/api/footprint/create-task?query=john@gmail.com&type=email" \ -H "X-API-KEY: YOUR_API_KEY" # 2. Poll until done (replace TASK_ID with the returned task_id) curl "https://www.osintcat.net/api/footprint/get-task?id=TASK_ID" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import time import requests BASE = "https://www.osintcat.net" HEADERS = {"X-API-KEY": "YOUR_API_KEY"} RUNNING = {"running", "queued", "pending", "processing", "started"} # 1. Create the task (charges one lookup) task = requests.get( f"{BASE}/api/footprint/create-task", params={"query": "john@gmail.com", "type": "email"}, headers=HEADERS, ).json() task_id = task["task_id"] # 2. Poll until the scan finishes while True: data = requests.get( f"{BASE}/api/footprint/get-task", params={"id": task_id}, headers=HEADERS, ).json() if str(data.get("status", "")).lower() not in RUNNING: break time.sleep(1) print(data) ``` ```javascript JS & TS theme={null} const BASE = 'https://www.osintcat.net'; const HEADERS = { 'X-API-KEY': 'YOUR_API_KEY' }; const RUNNING = ['running', 'queued', 'pending', 'processing', 'started']; const sleep = ms => new Promise(r => setTimeout(r, ms)); (async () => { // 1. Create the task (charges one lookup) const task = await fetch( `${BASE}/api/footprint/create-task?query=john@gmail.com&type=email`, { headers: HEADERS } ).then(r => r.json()); // 2. Poll until the scan finishes let data; do { data = await fetch( `${BASE}/api/footprint/get-task?id=${encodeURIComponent(task.task_id)}`, { headers: HEADERS } ).then(r => r.json()); if (!RUNNING.includes(String(data.status).toLowerCase())) break; await sleep(1000); } while (true); console.log(data); })(); ``` ```php PHP theme={null} $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $headers, ]); $response = curl_exec($curl); curl_close($curl); return json_decode($response, true); } // 1. Create the task (charges one lookup) $task = get_json("$base/api/footprint/create-task?query=john@gmail.com&type=email", $headers); $taskId = $task["task_id"]; // 2. Poll until the scan finishes do { $data = get_json("$base/api/footprint/get-task?id=" . urlencode($taskId), $headers); if (!in_array(strtolower($data["status"]), $running)) break; sleep(1); } while (true); print_r($data); ``` ```go Go theme={null} package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" "strings" "time" ) func getJSON(u string) map[string]interface{} { req, _ := http.NewRequest("GET", u, nil) req.Header.Set("X-API-KEY", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var out map[string]interface{} json.Unmarshal(body, &out) return out } func main() { base := "https://www.osintcat.net" running := map[string]bool{"running": true, "queued": true, "pending": true, "processing": true, "started": true} // 1. Create the task (charges one lookup) params := url.Values{} params.Add("query", "john@gmail.com") params.Add("type", "email") task := getJSON(base + "/api/footprint/create-task?" + params.Encode()) taskID, _ := task["task_id"].(string) // 2. Poll until the scan finishes var data map[string]interface{} for { data = getJSON(base + "/api/footprint/get-task?id=" + url.QueryEscape(taskID)) status, _ := data["status"].(string) if !running[strings.ToLower(status)] { break } time.Sleep(time.Second) } fmt.Printf("%+v\n", data) } ``` **Example Result (completed task)** ```json theme={null} { "status": "done", "stats": { "checked": 119, "total_modules": 119, "found": 95, "elapsed": "6.4s" }, "results": [ { "domain": "github.com", "taken": true, "ExtraData": { "Username": "johnny123", "PublicRepos": 42 } } ] } ``` # Email OSINT Source: https://docs.osintcat.net/api-reference/endpoint/email-osint GET https://www.osintcat.net/api/email-osint Where an e-mail address is registered, and in which breaches it appears Checks which websites and services an e-mail address is registered with and in which breaches it appears. Every request must state its purpose. > [!WARNING] > > A request without a purpose (parameter `purpose`, header `X-Purpose`, or `Purpose: ...` at the end of your User-Agent) is refused with `400 USER_AGENT_IDENTITY_REQUIRED`. ## Parameters **query** `string` *required* The e-mail address (`email` is accepted as well). **purpose** `string` Why you run the lookup, e.g. `fraud prevention`. Required unless sent as a header (below). ## Headers **X-API-KEY** `string` *required* Your API key. **X-Purpose** `string` The purpose, instead of the `purpose` parameter. ## Usage 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/email-osint?query=user%40example.com&purpose=fraud+prevention" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/email-osint" params = {"query": "user@example.com", "purpose": "fraud prevention"} 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/email-osint?query=user%40example.com&purpose=fraud+prevention", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/email-osint?query=user%40example.com&purpose=fraud+prevention", 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](/sdks). 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.email.lookup({ query: "user@example.com", purpose: "fraud prevention" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.email.lookup( query="user@example.com", purpose="fraud prevention", ) 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.LookupEmailRequest{ Query: "user@example.com", Purpose: "fraud prevention", } result, err := client.Email.Lookup(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} email->lookup( new LookupEmailRequest([ 'query' => 'user@example.com', 'purpose' => 'fraud prevention', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response Results for the same address may come from a cache for up to 15 minutes. **results** `object` What was found. **properties** **register** `array` Services the address is registered with. **breach** `array` Breaches the address appears in. **api** `array` Further findings from service lookups (profile names, pictures, account details). **\_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} { "results": { "register": [ { "site": "example-shop.com", "exists": true } ], "breach": [ { "name": "Example 2021", "date": "2021-04-02" } ], "api": [] }, "_meta": { "plan": "investigator", "lookups_left": 739 } } ``` ## Errors | Status | Error | When | | - | - | - | | 400 | `USER_AGENT_IDENTITY_REQUIRED` | No purpose given. | | 401 | `API key required` | No `X-API-KEY` header. | | 402 | `INSUFFICIENT_BALANCE` | The allowance is used up and your balance does not cover the lookup. | | 422 | `EMAIL_NOT_ALLOWED` | This address cannot be looked up. Not charged. | | 424 | `Provider Error` | The lookup could not be completed. Not charged. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # GitHub Profile Source: https://docs.osintcat.net/api-reference/endpoint/github GET https://www.osintcat.net/api/github-lookup Public GitHub profile by username Look up a GitHub account by its username and get the public profile. ## Parameters **username** `string` *required* The GitHub username. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/github-lookup?username=octocat" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/github-lookup" params = {"username": "octocat"} 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/github-lookup?username=octocat", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/github-lookup?username=octocat", 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](/sdks). 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.github.profile({ username: "octocat" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.github.profile( username="octocat", ) 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.ProfileGithubRequest{ Username: "octocat", } result, err := client.Github.Profile(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} github->profile( new ProfileGithubRequest([ 'username' => 'octocat', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response `taken` is `true` when the account exists. `ExtraData` holds what the profile shows publicly; a field the profile does not have is left out. When the lookup could not be completed, `taken` is `false` and `error` says why (for example `rate_limited`, try again later). **taken** `boolean` Whether an account with this username exists. **error** `string` Present only when the lookup could not be completed. **ExtraData** `object` Public profile fields. **properties** **Username** `string` Login. **Name** `string` Name. **Bio** `string` Bio. **Location** `string` Location. **Company** `string` Company. **Blog** `string` Website. **Email** `string` Public e-mail. **Twitter** `string` X/Twitter handle. **Followers** `number` Followers. **Following** `number` Following. **PublicRepos** `number` Public repositories. **CreatedAt** `string` Account creation. **ProfileUrl** `string` Profile link. **Repositories** `array` The 10 most recently pushed repositories (name, description, url, language, stars, forks). ```json 200 theme={null} { "taken": true, "ExtraData": { "Username": "octocat", "Name": "The Octocat", "Location": "San Francisco", "Followers": 21000, "PublicRepos": 8, "CreatedAt": "2011-01-25T18:44:36Z", "ProfileUrl": "https://github.com/octocat", "Repositories": [] } } ``` ## Errors | Status | Error | When | | - | - | - | | 400 | `Missing username parameter` | No `username` given. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # GTA Online Players Source: https://docs.osintcat.net/api-reference/endpoint/gta-players GET https://www.osintcat.net/api/gta/players Find GTA Online players by name or Rockstar ID > [!WARNING] > > This lookup is currently unavailable; requests fail with `424` and are not charged. Searches GTA Online players by display name or Rockstar ID (RID). Up to 200 results. ## Parameters **query** `string` *required* A player name or RID. **type** `string` (default: name) `name` (default) or `rid`. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/gta/players?query=example&type=name" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/gta/players" params = {"query": "example", "type": "name"} 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/gta/players?query=example&type=name", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/gta/players?query=example&type=name", 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)) } ``` ## Response **api** `string` Always `OsintCat`. **endpoint** `string` `gta/players`. **elapsed_ms** `number` Time taken. **timestamp** `string` When the search ran (UTC). **query** `string` The query. **search_type** `string` `name` or `rid`. **results_count** `number` Number of players found (`results` holds at most 200). **results** `array` Players. **properties** **rid** `integer` Rockstar ID. **name** `string` Display name. **platform** `string` Platform. **last_seen** `integer` Last seen (Unix time). **\_meta** `object` Your usage after this request. ## Errors | Status | Error | When | | - | - | - | | 424 | `GTA API request failed` | The player search is unavailable right now. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # GTA Online Sightings Source: https://docs.osintcat.net/api-reference/endpoint/gta-spotted GET https://www.osintcat.net/api/gta/spotted Where and when GTA Online players were seen > [!WARNING] > > This lookup is currently unavailable; requests fail with `424` and are not charged. Returns how often and when GTA Online players were seen in sessions, by display name or Rockstar ID. ## Parameters **query** `string` *required* A player name or RID. **type** `string` (default: name) `name` (default) or `rid`. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/gta/spotted?query=example&type=name" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/gta/spotted" params = {"query": "example", "type": "name"} 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/gta/spotted?query=example&type=name", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/gta/spotted?query=example&type=name", 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)) } ``` ## Response **results_count** `number` Number of players. **results** `array` Sightings. **properties** **rid** `integer` Rockstar ID. **name** `string` Display name. **platform** `string` Platform. **times_seen** `integer` How often the player was seen. **first_seen** `integer` First sighting (Unix time). **last_seen** `integer` Last sighting (Unix time). **last_seen_ts** `string` Last sighting, readable. **elapsed_ms** `number` Time taken. **\_meta** `object` Your usage after this request. ## Errors | Status | Error | When | | - | - | - | | 424 | `GTA API request failed` | The sightings search is unavailable right now. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Instagram Share Link Source: https://docs.osintcat.net/api-reference/endpoint/instagram-resolver GET https://www.osintcat.net/api/instagram-resolver Who shared an Instagram post or reel link Resolves an Instagram post or reel share link to the account that shared it and the author of the post. Profile links cannot be resolved. ## Parameters **link** `string` *required* An Instagram post or reel share link (with its `igsh` parameter). `url` or `query` are accepted as well. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/instagram-resolver?link=https%3A%2F%2Fwww.instagram.com%2Freel%2FCexample%2F%3Figsh%3DMWexample" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/instagram-resolver" params = {"link": "https://www.instagram.com/reel/Cexample/?igsh=MWexample"} 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/instagram-resolver?link=https%3A%2F%2Fwww.instagram.com%2Freel%2FCexample%2F%3Figsh%3DMWexample", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/instagram-resolver?link=https%3A%2F%2Fwww.instagram.com%2Freel%2FCexample%2F%3Figsh%3DMWexample", 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](/sdks). 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.instagram.resolveShareLink({ link: "https://www.instagram.com/reel/Cexample/?igsh=MWexample" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.instagram.resolve_share_link( link="https://www.instagram.com/reel/Cexample/?igsh=MWexample", ) 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.ResolveShareLinkInstagramRequest{ Link: "https://www.instagram.com/reel/Cexample/?igsh=MWexample", } result, err := client.Instagram.ResolveShareLink(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} instagram->resolveShareLink( new ResolveShareLinkInstagramRequest([ 'link' => 'https://www.instagram.com/reel/Cexample/?igsh=MWexample', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **success** `boolean` `true` when resolved. **author** `object` The account that posted it: `username`, `avatar`. **sharer** `object` The account that shared the link: `username`, `full_name`, `id`, `avatar`. **entity_id** `string` ID of the shared post. **\_meta** `object` Your usage after this request. ## Errors | Status | Error | When | | - | - | - | | 400 | `Provide a valid Instagram URL via ?link=...` | No link, not an Instagram link, or the link expired or points to a private post. Not charged. | | 422 | `profile_link` | A profile link: only post and reel share links can be resolved. Not charged. | | 424 | `(message)` | The link could not be resolved right now. Not charged. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # IP Lookup Source: https://docs.osintcat.net/api-reference/endpoint/ip GET https://www.osintcat.net/api/ip Open ports, services and location of an IP address Returns what is known about an IP address: open ports and services seen on it, hostnames, and its location and network. > [!NOTE] > > Results for the same address may come from a cache for up to two days. ## Parameters **query** `string` *required* An IPv4 or IPv6 address. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/ip?query=8.8.8.8" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/ip" params = {"query": "8.8.8.8"} 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/ip?query=8.8.8.8", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/ip?query=8.8.8.8", 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](/sdks). 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.ip.lookup({ query: "8.8.8.8" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.ip.lookup( query="8.8.8.8", ) 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.LookupIPRequest{ Query: "8.8.8.8", } result, err := client.IP.Lookup(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} ip->lookup( new LookupIpRequest([ 'query' => '8.8.8.8', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **ipleaks** `object` Services seen on the address: open ports, banners, hostnames, known vulnerabilities. `{"error": "No information available for that IP."}` when nothing was seen. **ipinfo** `object` Location and network: country, region, city, coordinates, time zone, ASN and organisation. ```json 200 theme={null} { "ipleaks": { "ip_str": "8.8.8.8", "ports": [ 53, 443 ], "hostnames": [ "dns.google" ], "org": "Google LLC" }, "ipinfo": { "ipAddress": "8.8.8.8", "countryName": "United States of America", "countryCode": "US", "cityName": "Mountain View", "asn": "15169", "asnOrganization": "Google LLC" } } ``` ## Errors See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Machine Viewer Source: https://docs.osintcat.net/api-reference/endpoint/machine-viewer GET https://www.osintcat.net/api/machine_viewer/stats Search machines from stealer logs, list their files and read or download them Machine Viewer holds machines from stealer logs: the files that were taken from each one, and the passwords, tokens, cookies and payment cards found in them. Search for a machine, list its files, and read or download them. > [!NOTE] > > Every Machine Viewer request counts as one lookup against your plan's daily allowance (Max: unlimited). When the allowance is used up, requests can continue at a per-lookup price charged to your balance. The price applies even when a search finds nothing; a search that fails because of an error on our side is not charged. Machine IDs are UUIDs; file IDs are 20 characters. *** ## Machine Viewer statistics ```bash theme={null} GET https://www.osintcat.net/api/machine_viewer/stats ``` How many machines, files, passwords, tokens, cookies and payment cards the Machine Viewer holds. **X-API-KEY** `string` *required* Your API key. **Response** ```json theme={null} { "total_machines": 100000, "total_files": 3000000, "total_passwords": 19000000, "total_unique_passwords": 13000000, "total_tokens": 150000, "total_cookies": 320000000, "total_credit_cards": 70000000, "total_size": 150000000000 } ``` ```bash cURL theme={null} curl "https://www.osintcat.net/api/machine_viewer/stats" \ -H "X-API-KEY: YOUR_API_KEY" ``` **SDK example** The same request with the [official SDKs](/sdks). 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.machineViewer.stats(); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.machine_viewer.stats() print(result) ``` ```go Go theme={null} package main import ( "context" "fmt" osintcatclient "github.com/OsintCatHQ/osintcat-go/client" ) func main() { client := osintcatclient.NewClient() // reads OSINTCAT_API_KEY result, err := client.MachineViewer.Stats(context.Background()) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} machineViewer->stats(); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` *** ## Search machines ```bash theme={null} GET https://www.osintcat.net/api/machine_viewer/search ``` Searches machines by name, username, hostname or machine ID. **query** `string` *required* What to search for: a name, username, hostname or machine ID. **X-API-KEY** `string` *required* Your API key. **Response** ```json theme={null} { "success": true, "query": "DESKTOP", "total": 1, "machines": [ { "id": "742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5", "name": "DESKTOP-EXAMPLE", "imported_at": "2026-08-17T01:30:15", "country": "DE", "ip": "203.0.113.7", "file_count": 24, "total_size": 1003638, "has_passwords": true, "password_count": 108, "unique_password_count": 50, "has_tokens": true, "token_count": 6, "has_cookies": true, "cookie_count": 7139, "has_credit_cards": false, "credit_card_count": 0 } ] } ``` ```bash cURL theme={null} curl "https://www.osintcat.net/api/machine_viewer/search?query=DESKTOP" \ -H "X-API-KEY: YOUR_API_KEY" ``` **SDK example** The same request with the [official SDKs](/sdks). 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.machineViewer.search({ query: "DESKTOP" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.machine_viewer.search( query="DESKTOP", ) 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.SearchMachineViewerRequest{ Query: "DESKTOP", } result, err := client.MachineViewer.Search(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} machineViewer->search( new SearchMachineViewerRequest([ 'query' => 'DESKTOP', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` *** ## Machine details ```bash theme={null} GET https://www.osintcat.net/api/machine_viewer/machines/{machine_id}/info ``` One machine, with the e-mail addresses and tokens found on it. **machine_id** `string` *required* Machine ID (a UUID), from `machineViewer.search`. **X-API-KEY** `string` *required* Your API key. **Response** ```json theme={null} { "success": true, "machine": { "id": "742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5", "name": "DESKTOP-EXAMPLE", "imported_at": "2026-08-17T01:30:15", "country": "DE", "ip": "203.0.113.7", "file_count": 24, "total_size": 1003638, "has_passwords": true, "password_count": 108, "unique_password_count": 50, "has_tokens": true, "token_count": 6, "has_cookies": true, "cookie_count": 7139, "has_credit_cards": false, "credit_card_count": 0 }, "emails": [ "user@example.com" ], "tokens": [ "example-token" ] } ``` ```bash cURL theme={null} curl "https://www.osintcat.net/api/machine_viewer/machines/742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5/info" \ -H "X-API-KEY: YOUR_API_KEY" ``` **SDK example** The same request with the [official SDKs](/sdks). 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.machineViewer.machine({ machine_id: "742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.machine_viewer.machine( machine_id="742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5", ) 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.MachineMachineViewerRequest{ MachineID: "742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5", } result, err := client.MachineViewer.Machine(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} machineViewer->machine( '742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5', ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` *** ## Machine files ```bash theme={null} GET https://www.osintcat.net/api/machine_viewer/machines/{machine_id}/files/treeview ``` Every file of a machine, with its path and size. Use a file's `id` with `machineViewer.file`. **machine_id** `string` *required* Machine ID (a UUID), from `machineViewer.search`. **X-API-KEY** `string` *required* Your API key. **Response** ```json theme={null} { "success": true, "tree": [ { "id": "aB3dE5fG7hI9jK1lM3nO", "name": "Passwords.txt", "path": "Browsers/Chrome/Passwords.txt", "size": 4096, "type": "file", "is_password_file": true, "is_token_file": false } ] } ``` ```bash cURL theme={null} curl "https://www.osintcat.net/api/machine_viewer/machines/742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5/files/treeview" \ -H "X-API-KEY: YOUR_API_KEY" ``` **SDK example** The same request with the [official SDKs](/sdks). 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.machineViewer.files({ machine_id: "742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.machine_viewer.files( machine_id="742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5", ) 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.FilesMachineViewerRequest{ MachineID: "742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5", } result, err := client.MachineViewer.Files(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} machineViewer->files( '742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5', ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` *** ## File content ```bash theme={null} GET https://www.osintcat.net/api/machine_viewer/files/{file_id}/info ``` One file, with its content as text. **file_id** `string` *required* File ID, from `machineViewer.files`. **X-API-KEY** `string` *required* Your API key. **Response** ```json theme={null} { "success": true, "info": { "id": "aB3dE5fG7hI9jK1lM3nO", "machine_id": "742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5", "machine_name": "DESKTOP-EXAMPLE", "path": "Browsers/Chrome/Passwords.txt", "filename": "Passwords.txt", "size": 4096, "content": "URL: https://example.com/login\nUsername: user@example.com\nPassword: hunter2", "is_password_file": true, "is_token_file": false } } ``` ```bash cURL theme={null} curl "https://www.osintcat.net/api/machine_viewer/files/aB3dE5fG7hI9jK1lM3nO/info" \ -H "X-API-KEY: YOUR_API_KEY" ``` **SDK example** The same request with the [official SDKs](/sdks). 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.machineViewer.file({ file_id: "aB3dE5fG7hI9jK1lM3nO" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.machine_viewer.file( file_id="aB3dE5fG7hI9jK1lM3nO", ) 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.FileMachineViewerRequest{ FileID: "aB3dE5fG7hI9jK1lM3nO", } result, err := client.MachineViewer.File(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} machineViewer->file( 'aB3dE5fG7hI9jK1lM3nO', ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` *** ## Download a file ```bash theme={null} GET https://www.osintcat.net/api/machine_viewer/files/{file_id}/download ``` The file itself, as it was in the log. **file_id** `string` *required* File ID, from `machineViewer.files`. **X-API-KEY** `string` *required* Your API key. **Response:** the file itself (`application/octet-stream`). ```bash cURL theme={null} curl "https://www.osintcat.net/api/machine_viewer/files/aB3dE5fG7hI9jK1lM3nO/download" \ -H "X-API-KEY: YOUR_API_KEY" -o file ``` **SDK example** The same request with the [official SDKs](/sdks). 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 response = await client.machineViewer.downloadFile({ file_id: "aB3dE5fG7hI9jK1lM3nO" }); const file = await response.arrayBuffer(); console.log(file.byteLength, "bytes"); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY data = b"".join(client.machine_viewer.download_file( file_id="aB3dE5fG7hI9jK1lM3nO", )) print(len(data), "bytes") ``` ```go Go theme={null} package main import ( "context" "fmt" "io" osintcat "github.com/OsintCatHQ/osintcat-go" osintcatclient "github.com/OsintCatHQ/osintcat-go/client" ) func main() { client := osintcatclient.NewClient() // reads OSINTCAT_API_KEY request := &osintcat.DownloadFileMachineViewerRequest{ FileID: "aB3dE5fG7hI9jK1lM3nO", } result, err := client.MachineViewer.DownloadFile(context.Background(), request) if err != nil { panic(err) } data, err := io.ReadAll(result) if err != nil { panic(err) } fmt.Println(len(data), "bytes") } ``` ```php PHP theme={null} machineViewer->downloadFile( 'aB3dE5fG7hI9jK1lM3nO', ); echo strlen($result), " bytes", PHP_EOL; ``` *** ## Download a machine ```bash theme={null} GET https://www.osintcat.net/api/machine_viewer/machines/{machine_id}/download ``` Every file of a machine in one ZIP archive. **machine_id** `string` *required* Machine ID (a UUID), from `machineViewer.search`. **X-API-KEY** `string` *required* Your API key. **Response:** the file itself (`application/zip`). ```bash cURL theme={null} curl "https://www.osintcat.net/api/machine_viewer/machines/742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5/download" \ -H "X-API-KEY: YOUR_API_KEY" -o machine.zip ``` **SDK example** The same request with the [official SDKs](/sdks). 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 response = await client.machineViewer.downloadMachine({ machine_id: "742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5" }); const file = await response.arrayBuffer(); console.log(file.byteLength, "bytes"); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY data = b"".join(client.machine_viewer.download_machine( machine_id="742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5", )) print(len(data), "bytes") ``` ```go Go theme={null} package main import ( "context" "fmt" "io" osintcat "github.com/OsintCatHQ/osintcat-go" osintcatclient "github.com/OsintCatHQ/osintcat-go/client" ) func main() { client := osintcatclient.NewClient() // reads OSINTCAT_API_KEY request := &osintcat.DownloadMachineMachineViewerRequest{ MachineID: "742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5", } result, err := client.MachineViewer.DownloadMachine(context.Background(), request) if err != nil { panic(err) } data, err := io.ReadAll(result) if err != nil { panic(err) } fmt.Println(len(data), "bytes") } ``` ```php PHP theme={null} machineViewer->downloadMachine( '742e1f66-f449-4a6c-80d5-8f5eb8e9c2b5', ); echo strlen($result), " bytes", PHP_EOL; ``` *** See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. An ID that is not valid is answered with `400`, an unknown one with `404 NOT_FOUND`. # Minecraft Player Source: https://docs.osintcat.net/api-reference/endpoint/minecraft GET https://www.osintcat.net/api/minecraft Minecraft profile, name history and leaked records in one call Combines the Minecraft profile of a player (UUID, name history, capes, skins) with records about them found in Minecraft server leaks. ## Parameters **query** `string` *required* A Minecraft username (or the value matching `type`). **type** `string` (default: username) What `query` is for the leak search: `username` (default), `uuid`, `email` or `ip`. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/minecraft?query=Notch" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/minecraft" params = {"query": "Notch"} 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/minecraft?query=Notch", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/minecraft?query=Notch", 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](/sdks). 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.minecraft.player({ query: "Notch" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.minecraft.player( query="Notch", ) 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.PlayerMinecraftRequest{ Query: "Notch", } result, err := client.Minecraft.Player(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} minecraft->player( new PlayerMinecraftRequest([ 'query' => 'Notch', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **query** `string` The query. **uuid** `string` Minecraft UUID, or `null`. **username** `string` Current username, or `null`. **name-history** `array` Earlier usernames. **capes** `array` Capes on the account. **skinHistory** `array` Skins the account has used. **results** `array | object` Records from Minecraft server leaks; `{"error": ...}` when the leak search was unavailable. ```json 200 theme={null} { "query": "notch", "uuid": "069a79f444e94726a5befca90e38aaf5", "username": "Notch", "name-history": [ { "name": "Notch" } ], "capes": [], "skinHistory": [], "results": [] } ``` ## Errors See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Minecraft Profile Source: https://docs.osintcat.net/api-reference/endpoint/minecraft-profile GET https://www.osintcat.net/api/minecraft-lookup-v2 Public Minecraft profile by username Look up a Minecraft account by its username and get the public profile. ## Parameters **username** `string` *required* The Minecraft username. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/minecraft-lookup-v2?username=Notch" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/minecraft-lookup-v2" params = {"username": "Notch"} 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/minecraft-lookup-v2?username=Notch", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/minecraft-lookup-v2?username=Notch", 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](/sdks). 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.minecraft.profile({ username: "Notch" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.minecraft.profile( username="Notch", ) 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.ProfileMinecraftRequest{ Username: "Notch", } result, err := client.Minecraft.Profile(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} minecraft->profile( new ProfileMinecraftRequest([ 'username' => 'Notch', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response `taken` is `true` when the account exists. `ExtraData` holds what the profile shows publicly; a field the profile does not have is left out. When the lookup could not be completed, `taken` is `false` and `error` says why (for example `rate_limited`, try again later). **taken** `boolean` Whether an account with this username exists. **error** `string` Present only when the lookup could not be completed. **ExtraData** `object` Public profile fields. **properties** **Username** `string` Current username. **UUID** `string` Minecraft UUID. **NameHistory** `array` Earlier usernames. **LabyUsername** `string` Username shown by the LabyMod profile, if any. **ProfilePicUrl** `string` Head render of the skin. ```json 200 theme={null} { "taken": true, "ExtraData": { "Username": "Notch", "UUID": "069a79f444e94726a5befca90e38aaf5", "NameHistory": [], "LabyUsername": "Notch", "ProfilePicUrl": "https://mc-heads.net/avatar/069a79f444e94726a5befca90e38aaf5" } } ``` ## Errors | Status | Error | When | | - | - | - | | 400 | `Missing username parameter` | No `username` given. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Modules Source: https://docs.osintcat.net/api-reference/endpoint/modules GET https://www.osintcat.net/api/modules Every module and whether your account can use it Lists every module with its current state and whether your account can use it. Use it to check access before calling a lookup: a lookup for a module your plan does not include is refused with `403 ACCESS_DENIED`. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage Does not count as a lookup. Needs the `osint:read` scope. ## Example request ```bash cURL theme={null} curl "https://www.osintcat.net/api/modules" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/modules" headers = {"X-API-KEY": "YOUR_API_KEY"} response = requests.get(url, headers=headers, timeout=60) print(response.status_code, response.json()) ``` ```javascript JS & TS theme={null} const response = await fetch("https://www.osintcat.net/api/modules", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/modules", 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](/sdks). 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.account.modules(); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.account.modules() print(result) ``` ```go Go theme={null} package main import ( "context" "fmt" osintcatclient "github.com/OsintCatHQ/osintcat-go/client" ) func main() { client := osintcatclient.NewClient() // reads OSINTCAT_API_KEY result, err := client.Account.Modules(context.Background()) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} account->modules(); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **modules** `array` One entry per module. **properties** **id** `string` Module id. **name** `string` Display name. **category** `string` Category it is listed under. **enabled** `boolean` Whether the module is switched on. **access_level** `string` `public`, `beta`, `staff` or `nobody`. **allowed_plans** `array` Plans the module is limited to (empty: all plans). **accessible** `boolean` Whether your account can use it right now. **locked** `boolean` Shown, but not usable on your plan. **user** `object` Your plan as the access check sees it. **properties** **plan** `string` Plan id. **role** `string` Account role. **beta_access** `boolean` Whether the account has beta access. ```json 200 theme={null} { "modules": [ { "id": "universal-breach-search", "name": "Universal Breach Search", "category": "Breach Data", "enabled": true, "access_level": "public", "allowed_plans": [], "accessible": true, "locked": false } ], "user": { "plan": "investigator", "role": "user", "beta_access": false } } ``` ## Errors | Status | Error | When | | - | - | - | | 401 | `Unauthorized` | Missing or unknown key. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Phone OSINT Source: https://docs.osintcat.net/api-reference/endpoint/phone-osint GET https://www.osintcat.net/api/phone-osint Carrier, line type and risk signals for a phone number Returns what is known about a phone number: whether it is valid, the carrier and line type, the country, linked online accounts and a risk score. ## Parameters **query** `string` *required* The phone number in international format, e.g. `+4915112345678`. Spaces and dashes are allowed. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/phone-osint?query=%2B4915112345678" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/phone-osint" params = {"query": "+4915112345678"} 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/phone-osint?query=%2B4915112345678", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/phone-osint?query=%2B4915112345678", 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](/sdks). 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.phone.lookup({ query: "+4915112345678" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.phone.lookup( query="+4915112345678", ) 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.LookupPhoneRequest{ Query: "+4915112345678", } result, err := client.Phone.Lookup(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} phone->lookup( new LookupPhoneRequest([ 'query' => '+4915112345678', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **module** `string` Always `phone`. **query** `string` The number in E.164 format. **found** `boolean` Whether anything was found. **risk** `object` Risk assessment. **properties** **score** `number` Score from 0 to 100, or `null`. **level** `string` `low`, `medium`, `high` or `unknown`. **summary** `array` The main facts as `{label, value}` pairs. **sections** `array` Detailed findings, grouped (carrier, location, linked accounts ...). **raw** `object` The full answer the summary is built from. **\_meta** `object` Your usage after this request (`plan`, `lookups_left`). ```json 200 theme={null} { "module": "phone", "query": "+4915112345678", "found": true, "risk": { "score": 12, "level": "low" }, "summary": [ { "label": "Number", "value": "+4915112345678" }, { "label": "Valid number", "value": "Yes" }, { "label": "Carrier", "value": "Telekom Deutschland" }, { "label": "Line type", "value": "Mobile" } ], "sections": [], "raw": {}, "_meta": { "plan": "investigator", "lookups_left": 740 } } ``` ## Errors | Status | Error | When | | - | - | - | | 400 | `phone_*` | The number cannot be a valid phone number; `code` says why (e.g. `phone_too_short`). | | 424 | `Upstream provider error` | The lookup could not be completed. | | 424 | `The request timed out.` | The lookup took too long. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Reddit Profile Source: https://docs.osintcat.net/api-reference/endpoint/reddit GET https://www.osintcat.net/api/reddit Public Reddit profile by username Look up a Reddit account by its username and get the public profile. ## Parameters **username** `string` *required* The Reddit username. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/reddit?username=unidan" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/reddit" params = {"username": "unidan"} 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/reddit?username=unidan", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/reddit?username=unidan", 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](/sdks). 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.reddit.profile({ username: "unidan" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.reddit.profile( username="unidan", ) 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.ProfileRedditRequest{ Username: "unidan", } result, err := client.Reddit.Profile(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} reddit->profile( new ProfileRedditRequest([ 'username' => 'unidan', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response `taken` is `true` when the account exists. `ExtraData` holds what the profile shows publicly; a field the profile does not have is left out. When the lookup could not be completed, `taken` is `false` and `error` says why (for example `rate_limited`, try again later). **taken** `boolean` Whether an account with this username exists. **error** `string` Present only when the lookup could not be completed. **ExtraData** `object` Public profile fields. **properties** **Username** `string` Username. **DisplayName** `string` Display name. **CommentKarma** `number` Comment karma. **LinkKarma** `number` Post karma. **TotalKarma** `number` Total karma. **CreatedAt** `number` Account creation (Unix time). **IsVerified** `boolean` Verified e-mail. **IsMod** `boolean` Moderates a community. **IsSuspended** `boolean` Present and `true` for suspended accounts. **ProfileUrl** `string` Profile link. ```json 200 theme={null} { "taken": true, "ExtraData": { "Username": "unidan", "DisplayName": "unidan", "CommentKarma": 1000000, "LinkKarma": 50000, "TotalKarma": 1050000, "CreatedAt": 1272498120, "IsVerified": true, "ProfileUrl": "https://reddit.com/user/unidan" } } ``` ## Errors | Status | Error | When | | - | - | - | | 400 | `Missing username parameter` | No `username` given. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Roblox Lookup Source: https://docs.osintcat.net/api-reference/endpoint/roblox GET https://www.osintcat.net/api/roblox Discord accounts linked to a Roblox account > [!WARNING] > > This lookup is currently unavailable; requests are refused with `403 ACCESS_DENIED`. Finds Discord accounts linked to a Roblox username. ## Parameters **query** `string` *required* A Roblox username. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/roblox?query=builderman" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/roblox" params = {"query": "builderman"} 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/roblox?query=builderman", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/roblox?query=builderman", 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)) } ``` ## Response ## Errors See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Steam Profile Source: https://docs.osintcat.net/api-reference/endpoint/steam GET https://www.osintcat.net/api/steam-lookup Public Steam profile by username Look up a Steam account by its username and get the public profile. ## Parameters **username** `string` *required* The Steam username. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/steam-lookup?username=gaben" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/steam-lookup" params = {"username": "gaben"} 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/steam-lookup?username=gaben", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/steam-lookup?username=gaben", 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](/sdks). 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.steam.profile({ username: "gaben" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.steam.profile( username="gaben", ) 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.ProfileSteamRequest{ Username: "gaben", } result, err := client.Steam.Profile(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} steam->profile( new ProfileSteamRequest([ 'username' => 'gaben', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response `taken` is `true` when the account exists. `ExtraData` holds what the profile shows publicly; a field the profile does not have is left out. When the lookup could not be completed, `taken` is `false` and `error` says why (for example `rate_limited`, try again later). **taken** `boolean` Whether an account with this username exists. **error** `string` Present only when the lookup could not be completed. **ExtraData** `object` Public profile fields. **properties** **Username** `string` Steam username. **DisplayName** `string` Profile name. **RealName** `string` Real name, if public. **ProfileUrl** `string` Profile link. **AvatarUrl** `string` Avatar. **ProfileState** `number` 1 when the profile is set up. **Visibility** `number` 3 = public, 1 = private. **TimeCreated** `number` Account creation (Unix time). **LastLogoff** `number` Last sign-off (Unix time). **CountryCode** `string` Country, if public. ```json 200 theme={null} { "taken": true, "ExtraData": { "Username": "gaben", "DisplayName": "Rabscuttle", "ProfileUrl": "https://steamcommunity.com/profiles/76561197960287930", "Visibility": 3, "TimeCreated": 1063407589, "CountryCode": "US" } } ``` ## Errors | Status | Error | When | | - | - | - | | 400 | `Missing username parameter` | No `username` given. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # TikTok Share Link Source: https://docs.osintcat.net/api-reference/endpoint/tiktok-resolver GET https://www.osintcat.net/api/tiktok-resolver Who shared a TikTok link Resolves a TikTok share link (e.g. `https://vm.tiktok.com/...`) to the account that shared it, with share details and the video. ## Parameters **link** `string` *required* A TikTok share link. `url` or `query` are accepted as well. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/tiktok-resolver?link=https%3A%2F%2Fvm.tiktok.com%2FZMexample%2F" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/tiktok-resolver" params = {"link": "https://vm.tiktok.com/ZMexample/"} 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/tiktok-resolver?link=https%3A%2F%2Fvm.tiktok.com%2FZMexample%2F", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/tiktok-resolver?link=https%3A%2F%2Fvm.tiktok.com%2FZMexample%2F", 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](/sdks). 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.tiktok.resolveShareLink({ link: "https://vm.tiktok.com/ZMexample/" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.tiktok.resolve_share_link( link="https://vm.tiktok.com/ZMexample/", ) 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.ResolveShareLinkTiktokRequest{ Link: "https://vm.tiktok.com/ZMexample/", } result, err := client.Tiktok.ResolveShareLink(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} tiktok->resolveShareLink( new ResolveShareLinkTiktokRequest([ 'link' => 'https://vm.tiktok.com/ZMexample/', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **success** `boolean` `true` when resolved. **sharer** `object` The account that shared the link: `username`, `nickname`, `avatar`, `region`, `language`, `account_created`, `follower_count`, `following_count`, `heart_count`, `video_count`, `bio`, `verified`, `private`. `resolved_via` is `sec_uid` for the sharer, or `video_author` when only the video's author could be identified. **share_info** `object` The share: `shared_from`, `share_time`, `device`, `language`, `region`, `account_created`. **video** `object` The video: `full_url`, `video_id`, `video_created`, `type`, `author_username`. ## Errors | Status | Error | When | | - | - | - | | 400 | `Provide a valid TikTok short link via ?link=...` | No link, or not a TikTok link. | | 404 | `No user found for this link` | The link carries no sharer. | | 424 | `Could not resolve link` | The link could not be resolved right now. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Twitch Profile Source: https://docs.osintcat.net/api-reference/endpoint/twitch GET https://www.osintcat.net/api/twitch Public Twitch profile by username Look up a Twitch account by its username and get the public profile. ## Parameters **username** `string` *required* The Twitch username. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/twitch?username=xqc" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/twitch" params = {"username": "xqc"} 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/twitch?username=xqc", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/twitch?username=xqc", 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](/sdks). 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.twitch.profile({ username: "xqc" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.twitch.profile( username="xqc", ) 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.ProfileTwitchRequest{ Username: "xqc", } result, err := client.Twitch.Profile(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} twitch->profile( new ProfileTwitchRequest([ 'username' => 'xqc', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response `taken` is `true` when the account exists. `ExtraData` holds what the profile shows publicly; a field the profile does not have is left out. When the lookup could not be completed, `taken` is `false` and `error` says why (for example `rate_limited`, try again later). **taken** `boolean` Whether an account with this username exists. **error** `string` Present only when the lookup could not be completed. **ExtraData** `object` Public profile fields. **properties** **Username** `string` Login name. **DisplayName** `string` Display name. **UserID** `string` Twitch user ID. **Description** `string` Bio. **ProfilePicUrl** `string` Profile picture. **Followers** `number` Followers. **CreatedAt** `string` Account creation. **BroadcasterType** `string` `partner`, `affiliate` or empty. **Banned** `boolean` Whether the account is suspended (`BanReason` then says why). **IsPartner** `boolean` Twitch partner. **IsAffiliate** `boolean` Twitch affiliate. **ProfileUrl** `string` Channel link. ```json 200 theme={null} { "taken": true, "ExtraData": { "Username": "xqc", "DisplayName": "xQc", "UserID": "71092938", "Followers": 12345678, "CreatedAt": "2014-09-12T23:50:05Z", "BroadcasterType": "partner", "Banned": false, "ProfileUrl": "https://twitch.tv/xqc" } } ``` ## Errors | Status | Error | When | | - | - | - | | 400 | `Missing username parameter` | No `username` given. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # X (Twitter) Profile Source: https://docs.osintcat.net/api-reference/endpoint/twitter GET https://www.osintcat.net/api/twitter-osint Public X profile, recent posts and an automated summary Returns the public profile of an X (Twitter) account and an automated, best-effort summary of its recent public posts (topics, language, tone, posting pattern). Treat the summary as unverified. ## Parameters **query** `string` *required* The X username, with or without `@`. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/twitter-osint?query=jack" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/twitter-osint" params = {"query": "jack"} 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/twitter-osint?query=jack", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/twitter-osint?query=jack", 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](/sdks). 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.x.profile({ query: "jack" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.x.profile( query="jack", ) 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.ProfileXRequest{ Query: "jack", } result, err := client.X.Profile(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} x->profile( new ProfileXRequest([ 'query' => 'jack', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **status** `string` `success`. **profile** `object` The public profile. **properties** **id** `string` Account ID. **username** `string` Handle. **name** `string` Display name. **created_at** `string` Account creation. **followers** `number` Followers. **following** `number` Following. **tweets_count** `number` Posts. **description** `string` Bio. **profile_image** `string` Profile picture. **banner_image** `string` Banner. **verified** `boolean` Verified. **recent_tweets_scraped** `number` How many recent posts the summary is based on. **ai_analysis** `object` The automated summary (interests, language, likely region, tone, activity pattern, authenticity estimate). Empty when no summary could be made. ```json 200 theme={null} { "status": "success", "profile": { "id": "12", "username": "jack", "name": "jack", "created_at": "2006-03-21", "followers": 6500000, "following": 3, "tweets_count": 30000, "verified": true }, "recent_tweets_scraped": 30, "ai_analysis": { "dominant_language": "English" } } ``` ## Errors | Status | Error | When | | - | - | - | | 404 | `User '...' not found on X (Twitter).` | No account with that username. Not charged. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Account Source: https://docs.osintcat.net/api-reference/endpoint/user GET https://www.osintcat.net/api/user Your plan, its daily allowance and what is left of it today Returns the account the API key belongs to: plan, plan expiry, and how many lookups are left today. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage Does not count as a lookup. Needs the `account:read` scope (keys with all scopes have it). ## Example request ```bash cURL theme={null} curl "https://www.osintcat.net/api/user" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/user" headers = {"X-API-KEY": "YOUR_API_KEY"} response = requests.get(url, headers=headers, timeout=60) print(response.status_code, response.json()) ``` ```javascript JS & TS theme={null} const response = await fetch("https://www.osintcat.net/api/user", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/user", 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](/sdks). 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.account.get(); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.account.get() print(result) ``` ```go Go theme={null} package main import ( "context" "fmt" osintcatclient "github.com/OsintCatHQ/osintcat-go/client" ) func main() { client := osintcatclient.NewClient() // reads OSINTCAT_API_KEY result, err := client.Account.Get(context.Background()) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} account->get(); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response **account_info** `object` The account. **properties** **username** `string` Username. **email** `string` E-mail address of the account. **plan** `string` Current plan, e.g. `Researcher`, `Investigator`, `Max`. **plan_expires** `string` When the plan ends (ISO 8601), `Lifetime`, or `N/A`. **usage** `object` Today's allowance. **properties** **request_limit_daily** `number` Lookups per day on this plan (Max: unlimited, shown as a very large number). **requests_remaining_today** `number` Lookups left today. Resets at 00:00 UTC. **api_access** `boolean` Whether the plan includes API access. ```json 200 theme={null} { "account_info": { "username": "analyst", "email": "analyst@example.com", "plan": "Investigator", "plan_expires": "2026-11-05T09:12:44" }, "usage": { "request_limit_daily": 750, "requests_remaining_today": 742, "api_access": true } } ``` ## Errors | Status | Error | When | | - | - | - | | 401 | `API key required` | No `X-API-KEY` header. | | 403 | `Invalid API key` | The key does not exist or was revoked. | | 403 | `insufficient_scope` | The key lacks the `account:read` scope. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Username Footprint Source: https://docs.osintcat.net/api-reference/endpoint/user-footprint GET https://www.osintcat.net/api/footprint/create-task Discover platform registrations for a username across 100+ services > [!WARNING] > > Footprint scans are currently unavailable; requests are refused with `403 ACCESS_DENIED`. The Username Footprint API checks whether a given username is registered across social media, gaming, and community platforms. It returns a summary and a per-platform breakdown including secondary metadata like profile IDs or account status where available. The lookup backend is load-balanced, so footprint scans run as **asynchronous tasks**: 1. **Create a task** with `GET /api/footprint/create-task` (this is where one lookup is charged). You receive a `task_id`. 2. **Poll the task** with `GET /api/footprint/get-task?id=` until `status` is no longer a running state. Polling is free. > [!NOTE] > > Username and email footprints share the same task endpoints — only the `type` parameter differs (`username` vs `email`). *** ## Step 1 — Create Task ```bash theme={null} GET https://www.osintcat.net/api/footprint/create-task ``` **query** `string` *required* The username to scan (e.g., `johndoe`) **type** `string` *required* (default: email) The footprint type. Use `username` for this endpoint. **X-API-KEY** `string` *required* Your API key > [!WARNING] > > Creating a task consumes exactly **one lookup** from your daily quota. Polling `get-task` does not. **Response Body** **task_id** `string` The identifier used to poll for results. **status** `string` The initial task status (e.g., `running`, `queued`, `pending`). **\_meta** `object` **properties** **plan** `string` Your current plan. **lookups_left** `string` Remaining lookups for the day (`unlimited` on the Max plan). ```json theme={null} { "task_id": "f3c8a1e2-9b44-4d51-bd0a-1c2e3f4a5b6c", "status": "running", "_meta": { "plan": "researcher", "lookups_left": 4821 } } ``` *** ## Step 2 — Poll Task ```bash theme={null} GET https://www.osintcat.net/api/footprint/get-task ``` **id** `string` *required* The `task_id` returned by `create-task`. **X-API-KEY** `string` *required* Your API key Poll roughly once per second until `status` is no longer one of the running states (`running`, `queued`, `pending`, `processing`, `started`). A scan typically completes within a few seconds and is capped at \~3 minutes. **Response Body** **status** `string` Current task status. While running it is one of `running`, `queued`, `pending`, `processing`, `started`. Any other value (e.g., `done`, `finished`) means the scan is complete. **stats** `object` Live progress / summary counters (populated as the scan runs). **properties** **checked** `number` Number of platforms checked so far. **total_modules** `number` Total number of platforms in the scan. **found** `number` Number of platforms where the username was found. **elapsed** `string` Elapsed scan time. **results** `array` List of platform results (grows as the scan progresses). **item properties** **domain** `string` Platform domain (e.g., `github.com`) **taken** `boolean` True if the username is registered on this platform **ExtraData** `object` Metadata retrieved from the platform (profile IDs, avatar URLs, follower counts, etc.) *** ## Example ```bash cURL theme={null} # 1. Create the task curl "https://www.osintcat.net/api/footprint/create-task?query=johndoe&type=username" \ -H "X-API-KEY: YOUR_API_KEY" # 2. Poll until done (replace TASK_ID with the returned task_id) curl "https://www.osintcat.net/api/footprint/get-task?id=TASK_ID" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import time import requests BASE = "https://www.osintcat.net" HEADERS = {"X-API-KEY": "YOUR_API_KEY"} RUNNING = {"running", "queued", "pending", "processing", "started"} # 1. Create the task (charges one lookup) task = requests.get( f"{BASE}/api/footprint/create-task", params={"query": "johndoe", "type": "username"}, headers=HEADERS, ).json() task_id = task["task_id"] # 2. Poll until the scan finishes while True: data = requests.get( f"{BASE}/api/footprint/get-task", params={"id": task_id}, headers=HEADERS, ).json() if str(data.get("status", "")).lower() not in RUNNING: break time.sleep(1) print(data) ``` ```javascript JS & TS theme={null} const BASE = 'https://www.osintcat.net'; const HEADERS = { 'X-API-KEY': 'YOUR_API_KEY' }; const RUNNING = ['running', 'queued', 'pending', 'processing', 'started']; const sleep = ms => new Promise(r => setTimeout(r, ms)); (async () => { // 1. Create the task (charges one lookup) const task = await fetch( `${BASE}/api/footprint/create-task?query=johndoe&type=username`, { headers: HEADERS } ).then(r => r.json()); // 2. Poll until the scan finishes let data; do { data = await fetch( `${BASE}/api/footprint/get-task?id=${encodeURIComponent(task.task_id)}`, { headers: HEADERS } ).then(r => r.json()); if (!RUNNING.includes(String(data.status).toLowerCase())) break; await sleep(1000); } while (true); console.log(data); })(); ``` ```php PHP theme={null} $url, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $headers, ]); $response = curl_exec($curl); curl_close($curl); return json_decode($response, true); } // 1. Create the task (charges one lookup) $task = get_json("$base/api/footprint/create-task?query=johndoe&type=username", $headers); $taskId = $task["task_id"]; // 2. Poll until the scan finishes do { $data = get_json("$base/api/footprint/get-task?id=" . urlencode($taskId), $headers); if (!in_array(strtolower($data["status"]), $running)) break; sleep(1); } while (true); print_r($data); ``` ```go Go theme={null} package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" "strings" "time" ) func getJSON(u string) map[string]interface{} { req, _ := http.NewRequest("GET", u, nil) req.Header.Set("X-API-KEY", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var out map[string]interface{} json.Unmarshal(body, &out) return out } func main() { base := "https://www.osintcat.net" running := map[string]bool{"running": true, "queued": true, "pending": true, "processing": true, "started": true} // 1. Create the task (charges one lookup) params := url.Values{} params.Add("query", "johndoe") params.Add("type", "username") task := getJSON(base + "/api/footprint/create-task?" + params.Encode()) taskID, _ := task["task_id"].(string) // 2. Poll until the scan finishes var data map[string]interface{} for { data = getJSON(base + "/api/footprint/get-task?id=" + url.QueryEscape(taskID)) status, _ := data["status"].(string) if !running[strings.ToLower(status)] { break } time.Sleep(time.Second) } fmt.Printf("%+v\n", data) } ``` **Example Result (completed task)** ```json theme={null} { "status": "done", "stats": { "checked": 112, "total_modules": 112, "found": 34, "elapsed": "5.1s" }, "results": [ { "domain": "github.com", "taken": true, "ExtraData": { "ProfileURL": "https://github.com/johndoe", "PublicRepos": 17 } }, { "domain": "reddit.com", "taken": false, "ExtraData": {} } ] } ``` # VIN Decoder Source: https://docs.osintcat.net/api-reference/endpoint/vin GET https://www.osintcat.net/api/vin Decode VINs and look up makes, models and manufacturers Decodes vehicle identification numbers and answers catalogue questions (makes, models, manufacturers, vehicle variables). Choose what to do with `type`. ## Parameters **type** `string` (default: decode) `decode` (default), `batch`, `wmi`, `makes`, `manufacturers`, `variables` or `canadian`. **query** `string` The VIN (`decode`), VINs separated by new lines, up to 50 (`batch`), a WMI (`wmi`), or the make / manufacturer / variable name the chosen `search_type` needs. Not needed for `makes`+`all`, `manufacturers`+`all`/`parts`, `variables`+`list` and `canadian`. **model_year** `number` `decode`: model year, improves accuracy. **extended** `boolean` `decode`: `true` for the extended field set. **search_type** `string` `makes`: `all`, `manufacturer`, `vehicletype`, `models`, `vehicletypes`. `manufacturers`: `all`, `details`, `wmis`, `parts`. `variables`: `list`, `values`. **year** `number` `makes` with `manufacturer`/`models`, and `canadian`: model year. **vehicle_type** `string` `makes`+`models` and `manufacturers`+`wmis`: vehicle type filter. **mfr_type** `string` `manufacturers`+`all`: manufacturer type filter. **page** `number` `manufacturers`+`all`/`parts`: page number. **parts_type** `string` `manufacturers`+`parts`: CFR part, default `565`. **from_date** `string` `manufacturers`+`parts`: start date (required there). **to_date** `string` `manufacturers`+`parts`: end date (required there). **make** `string` `canadian`: make. **model** `string` `canadian`: model. **units** `string` `canadian`: `Metric` (default) or `US`. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/vin?type=decode&query=1HGCM82633A004352" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/vin" params = {"type": "decode", "query": "1HGCM82633A004352"} 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/vin?type=decode&query=1HGCM82633A004352", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/vin?type=decode&query=1HGCM82633A004352", 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](/sdks). 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.vin.query({ query: "1HGCM82633A004352" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.vin.query( query="1HGCM82633A004352", ) 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.QueryVinRequest{ Query: osintcat.String( "1HGCM82633A004352", ), } result, err := client.Vin.Query(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} vin->query( new QueryVinRequest([ 'query' => '1HGCM82633A004352', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response The answer depends on `type`: `decode` and `wmi` return one object with the decoded fields (empty strings for fields the VIN does not carry); `batch` and the catalogue types return a list. Decoded VINs are cached for an hour. ```json 200 theme={null} { "VIN": "1HGCM82633A004352", "Make": "HONDA", "Model": "Accord", "ModelYear": "2003", "Manufacturer": "AMERICAN HONDA MOTOR CO., INC.", "BodyClass": "Coupe", "ABS": "" } ``` ## Errors | Status | Error | When | | - | - | - | | 400 | `query parameter is required` | `query` missing where the chosen type needs it. | | 400 | `Maximum 50 VINs allowed` | `batch` with more than 50 VINs. | | 400 | `Invalid query type / Invalid search_type` | Unknown `type` or `search_type`. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Xbox Profile Source: https://docs.osintcat.net/api-reference/endpoint/xbox GET https://www.osintcat.net/api/xbox-lookup Public Xbox profile by username Look up a Xbox account by its username and get the public profile. ## Parameters **username** `string` *required* The Xbox username. ## Headers **X-API-KEY** `string` *required* Your API key. ## Usage 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/xbox-lookup?username=Major+Nelson" \ -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests url = "https://www.osintcat.net/api/xbox-lookup" params = {"username": "Major Nelson"} 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/xbox-lookup?username=Major+Nelson", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); console.log(response.status, await response.json()); ``` ```php PHP theme={null} 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/xbox-lookup?username=Major+Nelson", 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](/sdks). 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.xbox.profile({ username: "Major Nelson" }); console.log(result); ``` ```python Python theme={null} from osintcat import OsintCat client = OsintCat() # reads OSINTCAT_API_KEY result = client.xbox.profile( username="Major Nelson", ) 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.ProfileXboxRequest{ Username: "Major Nelson", } result, err := client.Xbox.Profile(context.Background(), request) if err != nil { panic(err) } fmt.Printf("%+v\n", result) } ``` ```php PHP theme={null} xbox->profile( new ProfileXboxRequest([ 'username' => 'Major Nelson', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` ## Response `taken` is `true` when the account exists. `ExtraData` holds what the profile shows publicly; a field the profile does not have is left out. When the lookup could not be completed, `taken` is `false` and `error` says why (for example `rate_limited`, try again later). **taken** `boolean` Whether an account with this username exists. **error** `string` Present only when the lookup could not be completed. **ExtraData** `object` Public profile fields. **properties** **Gamertag** `string` Gamertag. **XUID** `string` Xbox user ID. **ProfileUrl** `string` Profile link. **AvatarUrl** `string` Gamer picture. **GamerScore** `string` Gamerscore. **AccountTier** `string` Account tier. **Bio** `string` Bio. **Location** `string` Location, if set. **Tenure** `string` Years of membership. **IsVerified** `boolean` Verified account. ```json 200 theme={null} { "taken": true, "ExtraData": { "Gamertag": "Major Nelson", "XUID": "2584878536129841", "GamerScore": "159520", "AccountTier": "Gold", "Tenure": "20" } } ``` ## Errors | Status | Error | When | | - | - | - | | 400 | `Missing username parameter` | No `username` given. | See [Errors](/api-reference/introduction#errors) for the responses every endpoint can return. # Introduction Source: https://docs.osintcat.net/api-reference/introduction Authentication, plans, limits, billing and errors for every OsintCat API endpoint The OsintCat API gives you the lookups of the OsintCat dashboard over HTTPS, with JSON responses. ## Base URL ``` https://www.osintcat.net/api ``` Every endpoint answers `GET` (most also accept `POST`); parameters always go in the query string. ## Authentication Send your API key in the `X-API-KEY` header with every request: ```bash theme={null} curl "https://www.osintcat.net/api/user" -H "X-API-KEY: YOUR_API_KEY" ``` Create keys in your account under **[Settings → Developer](https://www.osintcat.net/account/developer)**. A key is shown once, when you create it: store it then. Keys start with `oc_live_`; keys made before November 2026 start with `cat_` and keep working. Your account's CatID is not an API key. When you create a key you choose when it expires: in 7, 30 or 90 days, in a year, never, or on a date you pick. An expired key is refused like a revoked one (`403`); keys are not renewed, so create a new key and delete the old one. You can rename a key at any time. > [!WARNING] > > Treat a key like a password. Keep it on your server, never in a website, app or public repository. If a key may have leaked, revoke it in Settings → Developer and create a new one. ### Scopes Each key carries one or more scopes: | Scope | Allows | | - | - | | `*` | Everything (the default for a new key) | | `osint:read` | All lookups and [Modules](/api-reference/endpoint/modules) | | `account:read` | [Account](/api-reference/endpoint/user) | | `billing:read` | Your balance: `GET /api/_/user/balance` answers `{"balance": 12.5}` (euros) | A request outside the key's scopes is refused with `403 insufficient_scope`. ### Allowed IP addresses In Settings → Developer you can list the IP addresses your requests come from. With a list set, requests from any other address are refused with `403 IP_UNAUTHORIZED`. Leave the list empty to allow every address (for example for serverless platforms whose addresses change). A list holds up to 1 address on Researcher, 3 on Investigator and 10 on Max. ### Company and member keys In a company on OsintCat there are two more kinds of key. Both start with `oc_live_` and are sent the same way. * **Company keys** belong to the company. Owners and admins make them under **Company settings → API keys**. Lookups made with them are paid from the company balance at Enterprise prices and reach every module an Enterprise seat opens. They keep working when the person who made them leaves. Each key can have a monthly spending limit, and the company's own monthly limit counts what its keys spend. A company key has no person behind it: it is not limited by anyone's plan or allowed IP addresses, and [Account](/api-reference/endpoint/user) is not available with it. * **Member keys** are made by a member in **Settings → Developer** with **Use for** set to the company. They run as that member inside the company, exactly like the member's lookups in the dashboard: from the member's seat or the company balance. They stop working when the member leaves the company or loses their seat. Every lookup answer says who pays in the `X-Billed-To` header: `personal` or `company`. Lookups that return `_meta` also carry it as `_meta.billed_to`. ## Plans and daily allowance API access is part of these plans: | Plan | Lookups per day | API keys | | - | - | - | | Researcher | 300 | 1 | | Investigator | 750 | 3 | | Max | Unlimited | 5 | Free and Starter plans have no API access (`403 UPGRADE_REQUIRED`). Prices are on the [pricing page](https://www.osintcat.net/pricing). * Each lookup counts once against the daily allowance, including answers served from a cache. * The allowance resets at 00:00 UTC. [Account](/api-reference/endpoint/user) shows what is left; many lookups also return it in `_meta.lookups_left`. * [Account](/api-reference/endpoint/user), [Modules](/api-reference/endpoint/modules) and polling a task do not count. ### When the allowance is used up Most lookups continue at a per-lookup price charged to your account balance; the module's page in the dashboard shows the price. You are charged only when the lookup finds something, and never for a lookup that fails. Without enough balance the request is refused with `402 INSUFFICIENT_BALANCE`. Lookups that have no per-lookup price are refused with `429 LIMIT_REACHED` until the allowance resets. Each endpoint's page says how it is counted under **Usage**. ## Rate limits * **3 requests per second** per account, across all endpoints. Each company key has its own 3 per second. * **5,000 requests per hour** per endpoint from one IP address. Over a limit, the request is refused with `429 rate_limit`; the `Retry-After` header says how many seconds to wait. Keep well inside the limits: repeatedly exceeding them can pause API access for your account for a while. ## Responses Responses are JSON. A successful lookup answers `200` even when nothing was found; the endpoint's page shows how an empty result looks. Errors carry an `error` field, usually with a `message`, and every error answer names its `request_id`. A server error (`5xx`) also names an `error_id`. Quote them to support so we can find the request; the `X-Request-Id` header carries the request id on every response, successful ones included. ## Errors | Status | `error` | Meaning | | - | - | - | | 400 | `query error` and others | A required parameter is missing or invalid. | | 401 | `API key required` | No `X-API-KEY` header. | | 402 | `INSUFFICIENT_BALANCE` | The lookup would be charged and your balance does not cover it. | | 403 | `Unauthorized` / `Invalid API key` | The key does not exist, was revoked, or has expired. | | 403 | `insufficient_scope` | The key lacks the scope this endpoint needs. | | 403 | `UPGRADE_REQUIRED` | Your plan has no API access. | | 403 | `ACCESS_DENIED` | Your plan does not include this module, or it is currently unavailable. [Modules](/api-reference/endpoint/modules) shows which you can use. | | 403 | `IP_UNAUTHORIZED` | The request came from an address that is not on your allowed list. | | 403 | `ACCOUNT_REQUIRES_VERIFICATION` | Verify your account in the dashboard first. | | 403 | `account_frozen` | API access for the account is suspended; contact support. | | 403 | `ORG_INACTIVE` / `ORG_PAUSED` | Company and member keys: the company has no paid seats, or its subscription is unpaid. | | 403 | `ORG_BALANCE_EMPTY` | Company and member keys: the company balance does not cover the lookup. | | 403 | `ORG_LIMIT_ORG` / `ORG_LIMIT_KEY` | Company keys: the company's or the key's monthly spending limit is reached. | | 410 | `ENDPOINT_RETIRED` | The endpoint no longer exists. | | 429 | `LIMIT_REACHED` | The daily allowance is used up. | | 429 | `rate_limit` | Too many requests; see `Retry-After`. | | 500 | `internal_server_error` | Something failed on our side; quote the `error_id` and `request_id` to support. | | 424 | (varies) | The lookup could not be completed: a data source failed or was too slow. The `X-Upstream-Status` header says which (`502` or `504`). Not charged; quote the `request_id` to support. | | 503 | (varies) | The lookup is under maintenance. Not charged. | ## Endpoints > [card] [Account](/api-reference/endpoint/user) > > Plan and today's allowance > [card] [Modules](/api-reference/endpoint/modules) > > Which lookups your plan includes > [card] [Breach Lookup](/api-reference/endpoint/breach) > > Breach and leak indexes > [card] [Database Search](/api-reference/endpoint/database-search) > > Stealer logs and combo lists > [card] [Email OSINT](/api-reference/endpoint/email-osint) > > Where an address is registered > [card] [Phone OSINT](/api-reference/endpoint/phone-osint) > > Carrier, line type, risk > [card] [Machine Viewer](/api-reference/endpoint/machine-viewer) > > Infected machine records > [card] [IP Lookup](/api-reference/endpoint/ip) > > Services and location of an IP The navigation lists every endpoint. ## Responsible use Use the API only for lawful purposes such as security research, fraud prevention and investigations you are entitled to carry out, and in line with the [Terms of Service](https://www.osintcat.net/tos) and the data protection law that applies to you. # OsintCat API Source: https://docs.osintcat.net/index OSINT lookups, breach and leak search, and public records over a simple JSON API The OsintCat API gives your applications the lookups of the OsintCat dashboard: breach and leak search, e-mail and phone intelligence, infected machine records, gaming and social profiles, link resolvers and public records. > [card] [Quickstart](/quickstart) > > Create a key and make your first request in a few minutes. > [card] [Introduction](/api-reference/introduction) > > Authentication, plans, limits, billing and errors. > [card] [Get an API key](https://www.osintcat.net/account/developer) > > Keys are created in Settings → Developer. > [card] [Pricing](https://www.osintcat.net/pricing) > > API access comes with Researcher, Investigator and Max. > [card] [Dashboard](https://www.osintcat.net/dashboard) > > Run the same lookups in the browser. ## What you can look up > [card] [Breach Lookup](/api-reference/endpoint/breach) > > E-mails, usernames and passwords across breach indexes. > [card] [Database Search](/api-reference/endpoint/database-search) > > Stealer logs and combo lists by e-mail or domain. > [card] [Email OSINT](/api-reference/endpoint/email-osint) > > Where an address is registered. > [card] [Phone OSINT](/api-reference/endpoint/phone-osint) > > Carrier, line type, linked accounts and risk. > [card] [Machine Viewer](/api-reference/endpoint/machine-viewer) > > Infected machines, their files and extracted data. > [card] [Profiles](/api-reference/endpoint/github) > > GitHub, Reddit, X, Twitch, Steam, Xbox, Chess.com and Minecraft. ## Need help? Questions about the API go to [support](https://www.osintcat.net/support). Quote the `request_id` from an error answer (and the `error_id`, when there is one) so we can find the request. # Quickstart Source: https://docs.osintcat.net/quickstart Create an API key and make your first request ## 1. Get API access API access is part of the Researcher, Investigator and Max plans ([pricing](https://www.osintcat.net/pricing)). [Create an account](https://www.osintcat.net/register) if you have none. ## 2. Create a key 1. Open **[Settings → Developer](https://www.osintcat.net/account/developer)**. 2. Create a key, give it a name, and tick the scopes it needs (lookups, account, balance). With none ticked, the key gets all scopes. 3. Copy the key now: it is shown only once. > [!WARNING] > > Keep the key on your server. Anyone with it can run lookups on your account. ## 3. Check the key [Account](/api-reference/endpoint/user) does not count as a lookup: ```bash cURL theme={null} curl "https://www.osintcat.net/api/user" -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests response = requests.get( "https://www.osintcat.net/api/user", headers={"X-API-KEY": "YOUR_API_KEY"}, timeout=30, ) response.raise_for_status() data = response.json() print("Plan:", data["account_info"]["plan"]) print("Lookups left today:", data["usage"]["requests_remaining_today"]) ``` ```javascript JS & TS theme={null} const response = await fetch("https://www.osintcat.net/api/user", { headers: { "X-API-KEY": "YOUR_API_KEY" }, }); const data = await response.json(); console.log("Plan:", data.account_info.plan); console.log("Lookups left today:", data.usage.requests_remaining_today); ``` ```php PHP theme={null} true, CURLOPT_HTTPHEADER => ["X-API-KEY: YOUR_API_KEY"], ]); $data = json_decode(curl_exec($curl), true); curl_close($curl); echo "Plan: " . $data["account_info"]["plan"] . "\n"; echo "Lookups left today: " . $data["usage"]["requests_remaining_today"] . "\n"; ``` ```go Go theme={null} package main import ( "encoding/json" "fmt" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://www.osintcat.net/api/user", 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() var data struct { AccountInfo struct{ Plan string `json:"plan"` } `json:"account_info"` Usage struct{ Left int `json:"requests_remaining_today"` } `json:"usage"` } json.NewDecoder(resp.Body).Decode(&data) fmt.Println("Plan:", data.AccountInfo.Plan) fmt.Println("Lookups left today:", data.Usage.Left) } ``` ```json theme={null} { "account_info": { "username": "analyst", "email": "analyst@example.com", "plan": "Investigator", "plan_expires": "2026-11-05T09:12:44" }, "usage": { "request_limit_daily": 750, "requests_remaining_today": 750, "api_access": true } } ``` ## 4. Run a lookup ```bash cURL theme={null} curl "https://www.osintcat.net/api/breach?query=user@example.com" -H "X-API-KEY: YOUR_API_KEY" ``` ```python Python theme={null} import requests response = requests.get( "https://www.osintcat.net/api/breach", params={"query": "user@example.com"}, headers={"X-API-KEY": "YOUR_API_KEY"}, timeout=60, ) if response.status_code == 429: print("Slow down or wait for tomorrow's allowance:", response.json()) else: response.raise_for_status() result = response.json() print(result["results_count"], "records; lookups left:", result["_meta"]["lookups_left"]) ``` ```javascript JS & TS theme={null} const url = new URL("https://www.osintcat.net/api/breach"); url.searchParams.set("query", "user@example.com"); const response = await fetch(url, { headers: { "X-API-KEY": "YOUR_API_KEY" } }); const result = await response.json(); console.log(response.status, result.results_count, result._meta); ``` ```php PHP theme={null} "user@example.com"])); curl_setopt_array($curl, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["X-API-KEY: YOUR_API_KEY"], CURLOPT_TIMEOUT => 60, ]); $result = json_decode(curl_exec($curl), true); $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE); curl_close($curl); if ($status === 429) { echo "Slow down or wait for tomorrow's allowance\n"; } else { echo $result["results_count"] . " records; lookups left: " . $result["_meta"]["lookups_left"] . "\n"; } ``` ```go Go theme={null} package main import ( "encoding/json" "fmt" "net/http" "net/url" ) func main() { req, _ := http.NewRequest("GET", "https://www.osintcat.net/api/breach?query="+url.QueryEscape("user@example.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() if resp.StatusCode == 429 { fmt.Println("Slow down or wait for tomorrow's allowance") return } var result struct { Count int `json:"results_count"` Meta struct{ LookupsLeft any `json:"lookups_left"` } `json:"_meta"` } json.NewDecoder(resp.Body).Decode(&result) fmt.Println(result.Count, "records; lookups left:", result.Meta.LookupsLeft) } ``` ## Prefer an SDK? The [official SDKs](/sdks) send the key for you, read it from the `OSINTCAT_API_KEY` environment variable, and give every answer and error a type. The same lookup: ```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} breach->search( new SearchBreachRequest([ 'query' => 'user@example.com', ]), ); echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; ``` [Set up an SDK step by step](/sdks). ## Good practice * **Handle `429`.** Stay under 3 requests per second and wait for `Retry-After` when a request is refused. See [Rate limits](/api-reference/introduction#rate-limits). * **Check access first.** [Modules](/api-reference/endpoint/modules) shows which lookups your plan includes. * **Keep keys apart.** Use one key per application, with only the scopes it needs, so you can revoke one without stopping the others. * **Log `request_id`.** Every error answer names one, and a server error also an `error_id`; support can find the request with either. ## Next > [card] [Introduction](/api-reference/introduction) > > Plans, billing, limits and every error > [card] [Breach Lookup](/api-reference/endpoint/breach) > > The most used lookup # SDKs Source: https://docs.osintcat.net/sdks Official client libraries for the OsintCat API The official SDKs cover every endpoint you can use today, with typed requests and responses; endpoints marked unavailable are added when they return. They are open source (MIT) and send your key in the `X-API-KEY` header. > [tab] JS & TS > > **1. Create an API key** > > Under [Settings → Developer](https://www.osintcat.net/account/developer), create a key. Choose its scopes and how long it works. The key is shown once: copy it. > > **2. Install the SDK** > > Node.js 18 or later, Bun, Deno or Cloudflare Workers. No dependencies. > > ```sh theme={null} > npm install osintcat > ``` > > **3. Set your key** > > The SDK reads the key from the `OSINTCAT_API_KEY` environment variable. Keep it out of your code, and never ship it in a browser or mobile app. > > ```sh macOS / Linux theme={null} > export OSINTCAT_API_KEY="oc_live_..." > ``` > > ```powershell Windows theme={null} > $env:OSINTCAT_API_KEY = "oc_live_..." > ``` > > **4. Make your first request** > > Save this as `first.mjs` and run `node first.mjs`. It shows your plan and how many lookups are left today. > > ```typescript first.mjs theme={null} > import { OsintCatClient } from "osintcat"; > > const client = new OsintCatClient(); // reads OSINTCAT_API_KEY > > const result = await client.account.get(); > console.log(result); > ``` > > **5. Handle errors** > > Every answer other than 2xx raises an error with the status code and the answer, which names a `request_id` (a server error also an `error_id`): quote it to support. A lookup that fails is not charged. > > ```typescript theme={null} > import { OsintCat, OsintCatClient, OsintCatError } from "osintcat"; > > const client = new OsintCatClient(); > > try { > const result = await client.breach.search({ query: "user@example.com" }); > console.log(result.results_count); > } catch (err) { > if (err instanceof OsintCat.TooManyRequestsError) { > console.log("Daily allowance used up, or too many requests: try again later."); > } else if (err instanceof OsintCatError) { > // err.body carries error, message and request_id (plus error_id on a server error) > console.log(err.statusCode, err.body); > } else { > throw err; > } > } > ``` > > Every endpoint page shows its call in each language. Source and issues: [github.com/OsintCatHQ/osintcat-typescript](https://github.com/OsintCatHQ/osintcat-typescript). > [tab] Python > > **1. Create an API key** > > Under [Settings → Developer](https://www.osintcat.net/account/developer), create a key. Choose its scopes and how long it works. The key is shown once: copy it. > > **2. Install the SDK** > > Python 3.10 or later. Until the SDK is on PyPI, install it from GitHub: > > ```sh theme={null} > pip install "git+https://github.com/OsintCatHQ/osintcat-python@main" > ``` > > > [!WARNING] > > > > Do not `pip install osintcat` for now: that name on PyPI still holds an old client that does not work with the API. > > **3. Set your key** > > The SDK reads the key from the `OSINTCAT_API_KEY` environment variable. Keep it out of your code, and never ship it in a browser or mobile app. > > ```sh macOS / Linux theme={null} > export OSINTCAT_API_KEY="oc_live_..." > ``` > > ```powershell Windows theme={null} > $env:OSINTCAT_API_KEY = "oc_live_..." > ``` > > **4. Make your first request** > > Save this as `first.py` and run `python first.py`. It shows your plan and how many lookups are left today. > > ```python first.py theme={null} > from osintcat import OsintCat > > client = OsintCat() # reads OSINTCAT_API_KEY > > result = client.account.get() > print(result) > ``` > > **5. Handle errors** > > Every answer other than 2xx raises an error with the status code and the answer, which names a `request_id` (a server error also an `error_id`): quote it to support. A lookup that fails is not charged. > > ```python theme={null} > from osintcat import OsintCat > from osintcat.core.api_error import ApiError > from osintcat.errors import TooManyRequestsError > > client = OsintCat() > > try: > result = client.breach.search(query="user@example.com") > print(result.results_count) > except TooManyRequestsError: > print("Daily allowance used up, or too many requests: try again later.") > except ApiError as err: > # err.body carries error, message and request_id (plus error_id on a server error) > print(err.status_code, err.body) > ``` > > Every endpoint page shows its call in each language. Source and issues: [github.com/OsintCatHQ/osintcat-python](https://github.com/OsintCatHQ/osintcat-python). > [tab] Go > > **1. Create an API key** > > Under [Settings → Developer](https://www.osintcat.net/account/developer), create a key. Choose its scopes and how long it works. The key is shown once: copy it. > > **2. Install the SDK** > > Go 1.21 or later. > > ```sh theme={null} > go get github.com/OsintCatHQ/osintcat-go > ``` > > **3. Set your key** > > The SDK reads the key from the `OSINTCAT_API_KEY` environment variable. Keep it out of your code, and never ship it in a browser or mobile app. > > ```sh macOS / Linux theme={null} > export OSINTCAT_API_KEY="oc_live_..." > ``` > > ```powershell Windows theme={null} > $env:OSINTCAT_API_KEY = "oc_live_..." > ``` > > **4. Make your first request** > > Save this as `main.go` and run `go run .`. It shows your plan and how many lookups are left today. > > ```go main.go theme={null} > package main > > import ( > "context" > "fmt" > > osintcatclient "github.com/OsintCatHQ/osintcat-go/client" > ) > > func main() { > client := osintcatclient.NewClient() // reads OSINTCAT_API_KEY > result, err := client.Account.Get(context.Background()) > if err != nil { > panic(err) > } > fmt.Printf("%+v\n", result) > } > ``` > > **5. Handle errors** > > Every answer other than 2xx raises an error with the status code and the answer, which names a `request_id` (a server error also an `error_id`): quote it to support. A lookup that fails is not charged. > > ```go theme={null} > package main > > import ( > "context" > "errors" > "fmt" > > osintcat "github.com/OsintCatHQ/osintcat-go" > osintcatclient "github.com/OsintCatHQ/osintcat-go/client" > "github.com/OsintCatHQ/osintcat-go/core" > ) > > func main() { > client := osintcatclient.NewClient() > result, err := client.Breach.Search(context.Background(), &osintcat.SearchBreachRequest{Query: "user@example.com"}) > var limited *osintcat.TooManyRequestsError > var apiErr *core.APIError > switch { > case errors.As(err, &limited): > fmt.Println("Daily allowance used up, or too many requests: try again later.") > case errors.As(err, &apiErr): > // the error text carries the answer: error, message and request_id (plus error_id on a server error) > fmt.Println(apiErr.StatusCode, err) > case err != nil: > panic(err) > default: > fmt.Println(*result.ResultsCount) > } > } > ``` > > Every endpoint page shows its call in each language. Source and issues: [github.com/OsintCatHQ/osintcat-go](https://github.com/OsintCatHQ/osintcat-go). > [tab] PHP > > **1. Create an API key** > > Under [Settings → Developer](https://www.osintcat.net/account/developer), create a key. Choose its scopes and how long it works. The key is shown once: copy it. > > **2. Install the SDK** > > PHP 8.1 or later. The SDK sends requests through any PSR-18 HTTP client, such as Guzzle. > > ```sh theme={null} > composer require osintcat/osintcat-php guzzlehttp/guzzle > ``` > > **3. Set your key** > > The SDK reads the key from the `OSINTCAT_API_KEY` environment variable. Keep it out of your code, and never ship it in a browser or mobile app. > > ```sh macOS / Linux theme={null} > export OSINTCAT_API_KEY="oc_live_..." > ``` > > ```powershell Windows theme={null} > $env:OSINTCAT_API_KEY = "oc_live_..." > ``` > > **4. Make your first request** > > Save this as `first.php` and run `php first.php`. It shows your plan and how many lookups are left today. > > ```php first.php theme={null} > require __DIR__ . '/vendor/autoload.php'; > > use OsintCat\OsintCatClient; > > $client = new OsintCatClient(); // reads OSINTCAT_API_KEY > > $result = $client->account->get(); > echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL; > ``` > > **5. Handle errors** > > Every answer other than 2xx raises an error with the status code and the answer, which names a `request_id` (a server error also an `error_id`): quote it to support. A lookup that fails is not charged. > > ```php theme={null} > require __DIR__ . '/vendor/autoload.php'; > > use OsintCat\OsintCatClient; > use OsintCat\Breach\Requests\SearchBreachRequest; > use OsintCat\Exceptions\OsintcatApiException; > > $client = new OsintCatClient(); > > try { > $result = $client->breach->search(new SearchBreachRequest(['query' => 'user@example.com'])); > echo $result->resultsCount, PHP_EOL; > } catch (OsintcatApiException $e) { > if ($e->getCode() === 429) { > echo 'Daily allowance used up, or too many requests: try again later.', PHP_EOL; > } else { > // the body carries error, message and request_id (plus error_id on a server error) > echo $e->getCode(), ' ', json_encode($e->getBody()), PHP_EOL; > } > } > ``` > > Every endpoint page shows its call in each language. Source and issues: [github.com/OsintCatHQ/osintcat-php](https://github.com/OsintCatHQ/osintcat-php). ## Retries and timeouts The SDKs do not retry on their own. A lookup retried after a timeout may already have been counted or charged, and `429 LIMIT_REACHED` cannot succeed before the allowance resets at 00:00 UTC, so you decide when to try again. TypeScript and Python requests time out after 60 seconds; in Go pass a context with a deadline, and in PHP set `timeout` in the client options. ## Upgrading from osintcat 1.x Versions 1.x of the npm package were an older client that no longer works with the API. Version 2 is the SDK described here: `npm install osintcat@latest`.