---
title: "Search by File"
method: POST
path: "/search-by-file"
tags: ["Investigations"]
---

# Search by File

`POST /search-by-file`

Search for credentials based on file names.

## Request body

- object
  - `file_name` string, required — Name or partial name of files to search for. Supports both exact matches and partial matches. Case-insensitive. Examples include configuration files ('config.json'), credential files ('credentials.yml'), or key files ('id_rsa').
  - `cursor` string — Base64 encoded pagination cursor for retrieving the next set of results. Obtained from the 'nextCursor' field in the previous response. Enables efficient pagination through large result sets without skipping or duplicating records.
  - `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 monitoring new file exposures since a specific date.
  - `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 analyzing historical file exposures within a specific timeframe.
  - `sort_by` 'date_compromised' | 'date_uploaded' — Field to sort results by. 'date_compromised' sorts by when the file was captured during infection, while 'date_uploaded' sorts by when the file data was integrated into our platform.
  - `sort_direction` 'asc' | 'desc' — Direction to sort results. 'desc' returns newest file exposures first (recommended for threat monitoring), while 'asc' returns oldest exposures first (useful for forensic analysis and incident timelines).

## Response `200`

Successful file search

- FileResponse
  - `data` FileData[]
    - `_id` string
    - `stealer` string
    - `ip` string
    - `date_compromised` string, date-time
    - `date_uploaded` string, date-time
    - `matching_paths` unknown[]
      - unknown
    - `matching_items` unknown[]
      - unknown
  - `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)