---
title: "Search by IP/CIDR"
method: POST
path: "/search-by-ip"
tags: ["End User Protection"]
---

# Search by IP/CIDR

`POST /search-by-ip`

Search for compromises by IP address or CIDR range

## Request body

- union
  - object
    - `ips` string[], required — Array of IP addresses to search for (IPv4 or IPv6).
    - `sort_by` 'date_compromised' | 'date_uploaded' — Field to sort results by. 'date_compromised' sorts by when the infection occurred, while 'date_uploaded' sorts by when the data was integrated into our platform.
    - `sort_direction` 'asc' | 'desc' — Direction to sort results. 'desc' returns newest records first (recommended for monitoring), while 'asc' returns oldest records first (useful for historical analysis).
    - `types` string[] — Filter results by credential type. 'employees' returns corporate email credentials (@company.com), 'users' returns consumer credentials, and 'third_parties' returns credentials from related domains (only available when 'domains' parameter is provided).
    - `domains` string[] — List of domains to filter results by. Accepts root domains (example.com) and will match all subdomains. Maximum 50 domains per request. Required for 'third_parties' type filtering.
    - `keywords` string[] — Filter results to URLs containing specified keywords. Useful for finding credentials for specific services (e.g., ['vpn', 'admin', 'portal']). Case-insensitive matching. Maximum 10 keywords per request.
    - `keywords_match` 'any' | 'all' — Determines how multiple keywords are matched. 'any' returns results matching at least one keyword (broader results), while 'all' requires all keywords to match (narrower, more specific results).
    - `filter_credentials` boolean — Controls credential filtering in results. When true, returns only credentials matching the search criteria. When false, returns all credentials from matching stealers, which may include credentials for unrelated domains/services.
    - `cursor` string — Base64 encoded pagination cursor for retrieving the next set of results. Obtained from the 'nextCursor' field in the previous response. Provides more reliable pagination than offset-based approaches.
    - `start_date` string, date-time — ISO 8601 formatted timestamp (YYYY-MM-DDThh:mm:ssZ) to filter results from this date/time onward. Applies to the field specified in 'sort_by'. Useful for incremental data retrieval and monitoring.
    - `end_date` string, date-time — ISO 8601 formatted timestamp (YYYY-MM-DDThh:mm:ssZ) to filter results up to this date/time. Applies to the field specified in 'sort_by'. Useful for historical analysis and limiting result timeframes.
    - `additional_fields` string[] — Optional additional data to include in results. 'search_data' adds information about the search terms found in the browsing history search engine results from infected devices. 'installed_software' adds information about software installed on compromised machines, useful for vulnerability assessment and attack surface analysis. 'employee_session_cookies' adds session cookies from employee credentials, useful for identifying active sessions and potential unauthorized access. May increase response size and processing time. 'password_strength' adds password strength analysis for each password in the results. 'sensitive_applications' adds information about sensitive applications within the compromised URL structure, based on a predefined list of sensitive apps. 'dir_tree' adds information about the directory tree of the compromised machine, which can help identify potential attack vectors.
  - object
    - `cidr` string, required — CIDR range to search for.
    - `sort_by` 'date_compromised' | 'date_uploaded' — Field to sort results by. 'date_compromised' sorts by when the infection occurred, while 'date_uploaded' sorts by when the data was integrated into our platform.
    - `sort_direction` 'asc' | 'desc' — Direction to sort results. 'desc' returns newest records first (recommended for monitoring), while 'asc' returns oldest records first (useful for historical analysis).
    - `types` string[] — Filter results by credential type. 'employees' returns corporate email credentials (@company.com), 'users' returns consumer credentials, and 'third_parties' returns credentials from related domains (only available when 'domains' parameter is provided).
    - `domains` string[] — List of domains to filter results by. Accepts root domains (example.com) and will match all subdomains. Maximum 50 domains per request. Required for 'third_parties' type filtering.
    - `keywords` string[] — Filter results to URLs containing specified keywords. Useful for finding credentials for specific services (e.g., ['vpn', 'admin', 'portal']). Case-insensitive matching. Maximum 10 keywords per request.
    - `keywords_match` 'any' | 'all' — Determines how multiple keywords are matched. 'any' returns results matching at least one keyword (broader results), while 'all' requires all keywords to match (narrower, more specific results).
    - `filter_credentials` boolean — Controls credential filtering in results. When true, returns only credentials matching the search criteria. When false, returns all credentials from matching stealers, which may include credentials for unrelated domains/services.
    - `cursor` string — Base64 encoded pagination cursor for retrieving the next set of results. Obtained from the 'nextCursor' field in the previous response. Provides more reliable pagination than offset-based approaches.
    - `start_date` string, date-time — ISO 8601 formatted timestamp (YYYY-MM-DDThh:mm:ssZ) to filter results from this date/time onward. Applies to the field specified in 'sort_by'. Useful for incremental data retrieval and monitoring.
    - `end_date` string, date-time — ISO 8601 formatted timestamp (YYYY-MM-DDThh:mm:ssZ) to filter results up to this date/time. Applies to the field specified in 'sort_by'. Useful for historical analysis and limiting result timeframes.
    - `additional_fields` string[] — Optional additional data to include in results. 'search_data' adds information about the search terms found in the browsing history search engine results from infected devices. 'installed_software' adds information about software installed on compromised machines, useful for vulnerability assessment and attack surface analysis. 'employee_session_cookies' adds session cookies from employee credentials, useful for identifying active sessions and potential unauthorized access. May increase response size and processing time. 'password_strength' adds password strength analysis for each password in the results. 'sensitive_applications' adds information about sensitive applications within the compromised URL structure, based on a predefined list of sensitive apps. 'dir_tree' adds information about the directory tree of the compromised machine, which can help identify potential attack vectors.

## Response `200`

Successful search

- SearchResponse
  - `data` StealerData[]
    - `stealer` string
    - `employeeAt` string
    - `clientAt` string
    - `date_compromised` string, date-time
    - `date_uploaded` string, date-time
    - `stealer_family` string
    - `ip` string
    - `computer_name` string
    - `operating_system` string
    - `malware_path` string
    - `credentials` object[]
      - `url` string
      - `domain` string
      - `username` string
      - `password` string
      - `type` 'employee' | 'user' | 'third_party'
  - `nextCursor` string — Cursor for the next page of results

## Other responses

- `400` — Validation error - the request or request body was invalid
- `401` — Unauthorized - the server could not authenticate the request
- `403` — Forbidden - the server authenticated the request but refuses to process it because of insufficient permissions
- `404` — Not found - the server could not find the requested resource
- `408` — Timeout - the server timed out while waiting for a response (90 seconds)
- `429` — Rate limit exceeded - the server has received too many requests in a short period of time
- `500` — Internal server error - the server encountered an unexpected condition that prevented it from fulfilling the request

---

[API](https://skmtc.net/hudsonrock/apis/cavalier-api.md) · [All operations](https://skmtc.net/hudsonrock/apis/cavalier-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hudsonrock/cavalier-api/versions/5ba0142eec4d/schema)