---
title: "Search by Domains"
method: POST
path: "/search-by-domain"
tags: ["Domain Intelligence"]
---

# Search by Domains

`POST /search-by-domain`

Search for domain-wide compromises and intelligence

## Request body

- union
  - object — Search for domain-wide compromises and intelligence
    - `domains` string[], required — 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.
    - `subdomains` string[] — 🔍 Subdomain filters to match against subdomains in the URL field. Maximum 5 items allowed. ⚠️ Cannot be used together with 'keywords' or 'keywords_match' parameters - these are mutually exclusive filtering options.
    - `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).
    - `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 — Search for domains outside of your whitelisted domains
    - `external_domains` string[], required — List of third-party domains associated with your organization to search for. Ideal for SaaS platforms (company.salesforce.com), cloud services, or other external services your organization uses. Limited to 50 domains per request for performance reasons.
    - `sort_by` 'date_compromised' | 'date_uploaded' — Field to sort external domain results by. 'date_compromised' sorts by when the infection occurred (best for threat timeline analysis), while 'date_uploaded' sorts by when the data was integrated into our platform (best for monitoring new additions).
    - `sort_direction` 'asc' | 'desc' — Direction to sort external domain results. 'desc' returns newest records first (recommended for monitoring third-party risks), while 'asc' returns oldest records first (useful for establishing breach timelines).
    - `filter_credentials` boolean — Controls credential filtering for external domains. When true, returns only credentials matching the external domains. When false, returns all credentials from matching stealers, which may reveal additional third-party relationships and shadow IT usage.
    - `cursor` string — Base64 encoded pagination cursor for retrieving the next set of external domain results. Obtained from the 'nextCursor' field in the previous response. Essential for processing results from popular SaaS platforms with many compromises.
    - `start_date` string, date-time — ISO 8601 formatted timestamp (YYYY-MM-DDThh:mm:ssZ) to filter external domain results from this date/time onward. Applies to the field specified in 'sort_by'. Useful for monitoring third-party risks since a specific date.
    - `end_date` string, date-time — ISO 8601 formatted timestamp (YYYY-MM-DDThh:mm:ssZ) to filter external domain results up to this date/time. Applies to the field specified in 'sort_by'. Useful for analyzing historical third-party exposures within specific timeframes.
    - `additional_fields` string[] — Optional additional data to include in external domain 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, which can help identify vulnerable third-party applications and potential attack vectors. 'employee_session_cookies' adds session cookies from employee credentials, which can help identify active sessions and potential unauthorized access. '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/revisions/5ba0142eec4d/schema)