search_alerts
Search alerts using filters on severity, status, analyst verdict, date range, and more. Returns filtered alert lists with pagination support.
Instructions
Search alerts using advanced filters and criteria.
If a user is asking a "how many" type query, set the "first" field to 1 - "totalCount" is returned for any query.
Args: filters: JSON string containing an array of filter objects (optional). Each filter object must have: - fieldId: String field name (use flattened camelCase names below) - filterType: One of the supported filter types below - isNegated: Optional boolean to negate the filter (default: false)
Common Field Names (flattened camelCase):
- Core: "id", "severity", "status", "alertName", "detectedAt", "createdAt"
- Analysis: "analystVerdict", "assigneeUserId", "assigneeFullName", "alertNoteExists"
- Context: "storylineId", "description"
Filter Types and Required Keys:
String Filters (for severity, status, analystVerdict, etc.):
- "string_equals": Exact match. Requires "value" key.
Example: {"fieldId": "severity", "filterType": "string_equals", "value": "CRITICAL"}
- "string_in": Match any of multiple values. Requires "values" key (list).
Example: {"fieldId": "status", "filterType": "string_in", "values": ["NEW", "IN_PROGRESS"]}
Boolean Filters (for alertNoteExists, etc.):
- "boolean_equals": Exact match. Requires "value" key.
Example: {"fieldId": "alertNoteExists", "filterType": "boolean_equals", "value": true}
- "boolean_in": Match any of multiple values. Requires "values" key (list).
Example: {"fieldId": "alertNoteExists", "filterType": "boolean_in", "values": [true, false]}
Long Filters (for numeric IDs like assigneeUserId):
- "long_equals": Exact match. Requires "value" key.
Example: {"fieldId": "assigneeUserId", "filterType": "long_equals", "value": 123}
- "long_in": Match any of multiple values. Requires "values" key (list).
Example: {"fieldId": "assigneeUserId", "filterType": "long_in", "values": [1, 2, 3]}
DateTime Filters (for detectedAt, createdAt):
- "datetime_range": Range match using UNIX timestamps in milliseconds (UTC). Requires "start" and/or "end" keys.
Optional: "startInclusive", "endInclusive" (default: true)
IMPORTANT: All datetimes in the Alert API are in UTC timezone.
You MUST use the iso_to_unix_timestamp tool to convert ISO 8601 datetime strings
to UNIX timestamps (milliseconds) before using them in datetime filters.
IMPORTANT: Unless the user specifies a field to query a DateTime on, use createdAt.
The iso_to_unix_timestamp tool handles timezone conversion automatically.
Provide datetimes in the user's preferred timezone (e.g., "2024-10-30T08:00:00-04:00" for Eastern Time)
and the tool will convert to UTC milliseconds for the API.
Example workflow:
1. Call iso_to_unix_timestamp("2024-10-30T08:00:00-04:00") -> returns "1730289600000" (UTC)
2. Use result in filter: {"fieldId": "createdAt", "filterType": "datetime_range", "start": 1730289600000}
Example: {"fieldId": "createdAt", "filterType": "datetime_range", "start": 1730289600000}
Fulltext Search (for alertName, id, storylineId):
- "fulltext": Text search with case-insensitive substring matching. Requires "values" key (list).
Example: {"fieldId": "alertName", "filterType": "fulltext", "values": ["malware", "threat"]}
Limits:
- Maximum 50 filters per request
- Maximum 100 values in "values" arrays
first: Number of alerts to retrieve (1-100, default: 10).
after: Cursor for pagination (optional).
view_type: Filter by assignment - ALL, ASSIGNED_TO_ME, UNASSIGNED, MY_TEAM (default: ALL).
fields: Optional JSON string containing an array of field names to return.
If not specified, returns all default fields (including dataSources).
See list_alerts for available fields and dataSources behavior.
IMPORTANT - dataSources field behavior:
- When fields=None (default): dataSources is INCLUDED automatically
- When fields is provided: dataSources is ONLY included if explicitly requested
Example: '["id", "severity", "dataSources"]'Performance Note: When paging through many results, use fields='["id"]' for intermediate pages to conserve context window space. Use totalCount to gauge result set size.
Returns: Filtered list of alerts in JSON format.
Raises: RuntimeError: If there's an error searching alerts. ValueError: If parameters are invalid.
Examples: CORRECT: filters=[ {"fieldId": "severity", "filterType": "string_in", "values": ["CRITICAL", "HIGH"]}, {"fieldId": "status", "filterType": "string_equals", "value": "NEW"}, {"fieldId": "alertNoteExists", "filterType": "boolean_equals", "value": false} ]
WRONG:
filters=[
{"fieldId": "severity", "filterType": "EQUALS", "value": "CRITICAL"}, # Use "string_equals"
{"fieldId": "status.value", "filterType": "string_equals", "value": "NEW"} # Use "status" not "status.value"
]Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filters | No | ||
| first | No | ||
| after | No | ||
| view_type | No | ALL | |
| fields | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |