New API Endpoint: List Investigations with Pagination and Enhanced Filtering

We're excited to announce a new endpoint in our Public API that makes it easier to retrieve and filter your completed investigations programmatically.

What's New?

The new GET /v2/investigations endpoint provides a streamlined way to access your completed investigations with powerful filtering and pagination capabilities.

Key Features

• Paginated results - Efficiently retrieve large result sets
• Advanced filtering - Filter by source type, outcome, and date range
• Enhanced response data - Includes alert metadata, timestamps, and investigation outcomes
• Automatic exclusion - cloned alerts are automatically filtered out

Endpoint Details

Base URL

GET https://api.qevlar.com/v2/investigations

Query Parameters

All parameters are optional. If no filters are provided, the endpoint returns all completed investigations.

Filter Notes

• Date range: created_before_ts must be after created_after_ts
• Pagination: Defaults to page 1 with 25 results per page
• Multiple filters: Can be combined for precise results

Response Format

Success Response (200 OK)

{
  "alerts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "external_id": "INC-12345",
      "title": "Suspicious PowerShell Activity Detected",
      "source_type": "CROWDSTRIKE",
      "outcome": "MALICIOUS",
      "created_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:45:23Z"
    },
    {
      "id": "650e8400-e29b-41d4-a716-446655440001",
      "external_id": "ALT-67890",
      "title": "Unusual Network Traffic Pattern",
      "source_type": "SENTINEL",
      "outcome": "NOT_HARMFUL",
      "created_at": "2024-01-15T11:20:00Z",
      "completed_at": "2024-01-15T11:35:10Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "pages": 1,
    "offset": 0
  }
}

Response Fields

Alert Object

Pagination Object

Usage Examples

Example 1: Get All Investigations (First Page)

Request:

curl -X GET "https://api.qevlar.com/v2/investigations" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response: Returns the first 25 completed investigations with default pagination.

Example 2: Filter by Outcome

Get only malicious investigations:

Request:

curl -X GET "https://api.qevlar.com/v2/investigations?outcome=MALICIOUS" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example 3: Filter by Source Type

Get investigations from CrowdStrike only:

Request:

curl -X GET "https://api.qevlar.com/v2/investigations?source_type=CROWDSTRIKE" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example 5: Combined Filters with Pagination

Get malicious CrowdStrike alerts from the last week, page 2:

Request:

curl -X GET "https://api.qevlar.com/v2/investigations?source_type=CROWDSTRIKE&outcome=MALICIOUS&created_after_ts=1735862400&page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Best Practices

1. Use pagination for large result sets to avoid timeouts
2. Combine filters to narrow down results and improve performance
3. Cache results when appropriate to reduce API calls
4. Use date filters when building dashboards or reports for specific time periods
5. Check pagination.total to determine if you need to fetch additional pages
6. Store external_id for correlation with your source system records

Migration Guide

If you're currently using other methods to retrieve investigation data, this new endpoint provides:

• Better performance through optimized database queries
• More flexibility with multiple filter options
• Cleaner data with automatic exclusion of duplicates
• Richer metadata including timestamps and source identifiers

Questions or Feedback?

We'd love to hear how you're using this new endpoint! Reach out to our support team with any questions or suggestions for future enhancements.