Request body

JSON 
{
  "parameters": [
    {
      "name": "start_time",
      "value": "2024-01-01T00:00:00Z"
    },
    {
      "name": "domain",
      "comparisonOperator": "CONTAINS",
      "value": "example.com"
    }
  ],
  "response_columns": ["at_timestamp", "related.domain", "client.ip"]
}
Field Required Description
parameters Yes Array of parameter entries. Each entry must have a name and value.
response_columns Conditional List of column names to include in the response. If the query defines default columns, this field is optional — omit it to receive those defaults. If the query defines no defaults, this field is required. Omitting it returns a 400 Bad Request.

Parameters

Each entry in the parameters array has the following shape:

Field Required Description
name Yes The parameter name as listed in the query definition
value Yes The value to filter on. Can be a string, number, or array (when the parameter supports it)
comparisonOperator No How to compare the value. Only valid when the query parameter declares allowed_operators (check via Describe a predefined query). Supplying an operator for a parameter that does not declare allowed_operators returns a 400 Bad Request error.
Note: Duplicate parameter names in a single request are rejected.

Comparison operators

When a query parameter declares allowed_operators, you may specify how your value is matched. The following operators are supported:

Operator Behavior
EQ Exact match. The observation field must equal the supplied value.
IN Match any value in the supplied list. Use this with an array value.
CONTAINS The observation field must contain the supplied string as a substring (case-sensitive partial match).
Note: Operator matching is case-insensitive — EQ, eq, and Eq are all accepted.

To check whether a parameter supports comparison operators, call the Describe a predefined query endpoint and inspect the allowed_operators field on the parameter object. If the field is absent or empty, that parameter does not support comparison operators — attempting to supply a comparisonOperator for such a parameter will result in a 400 Bad Request error instructing you to remove the field.

Selecting response columns

Use response_columns to specify which columns to include in the response. If omitted, the query returns its default columns (if defined).

JSON 
{
  "response_columns": ["at_timestamp", "client.ip", "server.ip", "host.hostname"]
}
  • Use the Describe a predefined query endpoint to discover the full list of valid column names from the default_columns array.
  • Supplying an unrecognised column name returns a 400 Bad Request error.
  • Supplying an empty array ([]) returns a 400 Bad Request error. You must provide at least one column name.
  • If the query defines default_columns, you may omit response_columns entirely to receive those defaults.
  • If the query defines no default_columns, then response_columns is required. Omitting it returns a 400 Bad Request with the message response_columns is required for this query.