Search and filter detections

Overview¶

Use Query.detectionSearch to search detections. The in argument accepts a QL expression, an offset, and a result limit.

The QL syntax is the same syntax used by Advanced Search. Start with a narrow time range while you test a query. Then add only the fields your integration needs to the selection set.

Search with QL¶

The cql_query value contains the detection source, filters, and time range:

The QL source keyword remains alert for this API. It identifies detection records.

query SearchDetections($in: SearchRequestInput) {
  detectionSearch(in: $in) {
    status
    reason
    alerts {
      total_results
      list {
        id
        status
        metadata { title severity created_at { seconds nanos } }
      }
    }
  }
}

{
  "variables": {
    "in": {
      "cql_query": "from alert where status = 'OPEN' and severity >= 0.6 earliest=-1d",
      "limit": 100,
      "offset": 0
    }
  }
}

Paginate results¶

For a result set below 10,000 detections, request each page with offset and limit. The response includes total_results, which counts all matching detections.

For larger result sets, the response includes search_id. Pass it to Query.detectionPoll. When search_id is present, the API ignores offset and limit and returns the next result part.

Keep fetching parts until the API returns no next part. Confirm that the number of detections received matches total_results.

Apply tenant service filters¶

For a tenant scope that includes child tenants, use tenant_service_filters. The filter limits results to tenants with the requested services. The request uses the tenant context from the X-Tenant-Context header when that scope applies to your account.

Check the generated SearchRequestInput reference for the current input fields.