---
title: "Search by Term"
method: POST
path: "/search-by-term"
tags: ["Investigations"]
---

# Search by Term

`POST /search-by-term`

Search for terms found in browsing history search engine results from infected devices.

## Request body

- object
  - `search_terms` string[] — List of terms to search for in the browsing history. Between 1-10 terms required per request.
  - `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 data loss.
  - `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 term search

- TermResponse
  - `data` TermData[]
    - `search_query` string
    - `search_engine` string
    - `timestamp` string
  - `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)