Method: legacy.legacyFetchUdmSearchView

Full name: projects.locations.instances.legacy.legacyFetchUdmSearchView

Legacy endpoint for fetching events, filters, and histograms matching UDM search.

HTTP request

POST https://chronicle.googleapis.com/v1alpha/{instance}/legacy:legacyFetchUdmSearchView

Path parameters

Parameters
instance

string

Required. Chronicle instance this request is sent to. Format: projects/{project}/locations/{location}/instances/{instance}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "baseline_query": string,
  "snapshot_query": string,
  "baseline_time_range": {
    object (Interval)
  },
  "snapshot_time_range": {
    object (Interval)
  },
  "event_list": {
    object (UdmEventListOptions)
  },
  "timeline": {
    object (EventCountTimelineOptions)
  },
  "field_aggregations": {
    object (UdmFieldAggregationsOptions)
  },
  "case_insensitive": boolean,
  "generate_ai_overview": boolean,
  "return_operation_id_only": boolean,
  "detection_options": {
    object (DetectionOptions)
  },
  "stats_function_parameter": {
    object (FunctionParameter)
  },
  "draft_data_access_scope": {
    object (DataAccessScope)
  },
  "prevalence": {
    object (UdmPrevalenceOptions)
  },
  "enable_poc_fast_path": boolean
}
Fields
baseline_query

string

Required. Boolean query to search for events. You can refer to https://cloud.google.com/chronicle/docs/investigation/udm-search for the query syntax. Example: 'ip=/172.*/ AND metadata.event_type!="NETWORK_CONNECTION" AND ( target.ip = "3.225.179.73" OR target.ip = "23.47.48.70")'
snapshot_query

string

Query applied to the baseline query's events. In other words, this query is applied to the Snapshot produced from the baseline query. The snapshot_query has the same syntax as baseline_query and is implicitly ANDed with baseline_query to produce events.
baseline_time_range

object (Interval)

Required. Required, the time range to search for [inclusive start time, exclusive end time).
snapshot_time_range

object (Interval)

The time range to filter for [inclusive start time, exclusive end time). This time range must be completely within baseline_time_range. If not set, it is assumed to match baseline_time_range.
event_list

object (UdmEventListOptions)

Parameters for the Events that will be streamed back.
timeline

object (EventCountTimelineOptions)

Parameters for the EventCountTimeline that will be streamed back.
field_aggregations

object (UdmFieldAggregationsOptions)

Parameters for the Aggregated UDM fields that will be streamed back.
case_insensitive

boolean

If true, the search should be performed in a case-insensitive manner.
generate_ai_overview

boolean

Optional. If true, generate AI overview for the search results.
return_operation_id_only

boolean

Optional. If this field is set to true, the response will only contain the operation resource name. The actual search results (events) will be streamed back when the client invokes the streamSearchOperation method using this operation resource name.
detection_options

object (DetectionOptions)

Fetch alerts/detections relevant to the search result.
stats_function_parameter

object (FunctionParameter)

The request to apply statistical function on filtered data.
draft_data_access_scope

object (DataAccessScope)

Data access scope used to filter events. This is intended to be used by admins to preview in-development scopes. Should only be called by users with global access. If the caller does not have global access, the request will fail.
prevalence

object (UdmPrevalenceOptions)

Parameters to get prevalence counts on Events returned by UDM Search
enable_poc_fast_path

boolean

If true, search will limit max_baseline_results to 30K events and remove time-order guarantee (i.e., results may not be the most-recent events in baseline query time range). In this mode, replayed search queries are not guaranteed to yield the same results each time. This option is for poc use-cases only.

Response body

Depending on the parameters in ListUdmEventsV3Request, stream back some combination of UDM Events, EventCountTimeline, and UdmFieldAggregations.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "operation": string,
  "progress": number,
  "too_many_events": boolean,
  "too_large_response": boolean,
  "complete": boolean,
  "valid_baseline_query": boolean,
  "baseline_events_count": integer,
  "valid_snapshot_query": boolean,
  "query_validation_errors": [
    {
      object (ErrorMessage)
    }
  ],
  "runtime_errors": [
    {
      object (RuntimeError)
    }
  ],
  "filtered_events_count": integer,
  "stats_function_parameter_validation_error_message": string,
  "prevalence": {
    object (UdmPrevalenceResponse)
  },
  "stats": {
    object (Stats)
  },
  "data_sources": [
    enum (SearchDataSource)
  ],
  "ai_overview": {
    object (AIOverview)
  },
  "events": {
    object (UdmEventList)
  },
  "timeline": {
    object (EventCountTimeline)
  },
  "field_aggregations": {
    object (UdmFieldAggregations)
  },
  "grouped_field_aggregations": {
    object (UdmFieldAggregations)
  },
  "detections": {
    object (Detections)
  },
  "stats_function_response": {
    object (FunctionResponse)
  },
  "activity_timeline": {
    object (EventCountTimeline)
  }
}
Fields
operation

string

The name of the operation resource representing the UDM Search operation. This can be passed to StreamSearchOperation to fetch stored results or stream the results of an in-progress operation.

The metadata type of the operation is UdmSearchMetadata. The response type is LegacyFetchUdmSearchViewResponse.

Format: projects/{project}/locations/{location}/instances/{instance}/operations/{operation}
progress

number

Progress of the query represented as a double between 0 and 1.
too_many_events

boolean

If true, there are too many events to return and some have been omitted.
too_large_response

boolean

If true, the response to be returned to the UI is too large and some events have been omitted.
complete

boolean

Streaming for this response is done. There will be no additional updates.
valid_baseline_query

boolean

Indicates whether the request baseline_query is a valid structured query or not. If not, query_validation_errors will include the parse error.
baseline_events_count

integer

The number of events in the baseline query.
valid_snapshot_query

boolean

Indicates whether the request baseline and snapshot queries are valid. If not, query_validation_errors will include the parse error.
query_validation_errors[]

object (ErrorMessage)

Parse error for the baseline_query and/or the snapshot_query.
runtime_errors[]

object (RuntimeError)

Runtime errors.
filtered_events_count

integer

The number of events in the snapshot that match the snapshot_query. This is <= baseline_events_count. If the snapshot query is empty this will be equivalent to baseline_events_count.
stats_function_parameter_validation_error_message

string

If the request's stats_function_parameter` is invalid, this field will contain the detailed error message.
prevalence

object (UdmPrevalenceResponse)

Prevalence results on Events returned by UDM Search
stats

object (Stats)

Stats results when the query is for statistics
data_sources[]

enum (SearchDataSource)

Datasource of the query and results in case of a statistics query
ai_overview

object (AIOverview)

AI generated overview for the search results. Only populated if the AI features are enabled for the customer and generate_ai_overview is set to true in the request.
events

object (UdmEventList)

List of UDM events. NOTE: After complete is set to true, the UdmEventList message will be omitted from the response. The latest message should be used as reference. If the UdmEventList message is returned again, then it should replace the previous value.
timeline

object (EventCountTimeline)

Timeline of event counts broken into buckets.
field_aggregations

object (UdmFieldAggregations)

List of UDM fields with aggregated values.
grouped_field_aggregations

object (UdmFieldAggregations)

List of grouped fields with aggregated values.
detections

object (Detections)

List of relevant detections, if detection_list.max_returned_detections was set.
stats_function_response

object (FunctionResponse)

Result for statistical function.
activity_timeline

object (EventCountTimeline)

Timeline of event counts broken into hourly/daily buckets to identify activity.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the instance resource:

  • chronicle.legacies.legacyFetchUdmSearchView

For more information, see the IAM documentation.

UdmEventListOptions

JSON representation 
{
  "max_returned_events": integer
}
Fields
max_returned_events

integer

EventCountTimelineOptions

This type has no fields.

UdmFieldAggregationsOptions

JSON representation 
{
  "max_values_per_field": integer
}
Fields
max_values_per_field

integer

DetectionOptions

JSON representation 
{
  "snapshot_query": string,
  "detection_list": {
    object (DetectionListOptions)
  },
  "field_aggregations": {
    object (UdmFieldAggregationsOptions)
  }
}
Fields
snapshot_query

string
detection_list

object (DetectionListOptions)
field_aggregations

object (UdmFieldAggregationsOptions)

DetectionListOptions

JSON representation 
{
  "max_returned_detections": integer
}
Fields
max_returned_detections

integer

FunctionParameter

JSON representation 
{
  "grouped_fields": [
    {
      object (GroupByField)
    }
  ],
  "selected_fields": [
    {
      object (SelectedField)
    }
  ],
  "orders": [
    {
      object (OrderBy)
    }
  ],
  "max_returned_rows": integer
}
Fields
grouped_fields[]

object (GroupByField)
selected_fields[]

object (SelectedField)
orders[]

object (OrderBy)
max_returned_rows

integer (uint32 format)

GroupByField

JSON representation 
{
  "udm_field_path": string,
  "to_lower_case": boolean,

  // Union field transformation can be only one of the following:
  "resolution_in_nano_seconds": string,
  "cidr_prefix_length_in_bits": integer,
  "top_n_level_domain": integer,
  "get_registered_domain": boolean
  // End of list of possible types for union field transformation.
}
Fields
udm_field_path

string
to_lower_case

boolean

Union field transformation.

transformation can be only one of the following:
resolution_in_nano_seconds

string
cidr_prefix_length_in_bits

integer (uint32 format)
top_n_level_domain

integer (uint32 format)
get_registered_domain

boolean

SelectedField

JSON representation 
{
  "udm_field_path": string,
  "function_type": enum (FunctionType),
  "percentile": number
}
Fields
udm_field_path

string
function_type

enum (FunctionType)
percentile

number

FunctionType

Enums
FUNCTION_TYPE_UNSPECIFIED
FUNCTION_TYPE_SUM
FUNCTION_TYPE_COUNT
FUNCTION_TYPE_COUNT_DISTINCT
FUNCTION_TYPE_AVERAGE
FUNCTION_TYPE_STDDEV
FUNCTION_TYPE_MIN
FUNCTION_TYPE_MAX

OrderBy

JSON representation 
{
  "field_index": integer,
  "is_descending_order": boolean
}
Fields
field_index

integer (uint32 format)
is_descending_order

boolean

UdmPrevalenceOptions

JSON representation 
{
  "get_prevalence": boolean,
  "bucket_size": {
    object (UdmSearchAggregationBucketFunction)
  }
}
Fields
get_prevalence

boolean
bucket_size

object (UdmSearchAggregationBucketFunction)

UdmSearchAggregationBucketFunction

JSON representation 
{
  "resolution_in_seconds": integer
}
Fields
resolution_in_seconds

integer

UdmEventList

JSON representation 
{
  "events": [
    {
      object (UdmEventInfo)
    }
  ],
  "column_names": {
    object (ColumnNames)
  },
  "progress": number,
  "too_many_events": boolean,
  "complete": boolean
}
Fields
events[]

object (UdmEventInfo)
column_names

object (ColumnNames)
progress

number
too_many_events

boolean
complete

boolean

ColumnNames

JSON representation 
{
  "names": [
    string
  ]
}
Fields
names[]

string

EventCountTimeline

JSON representation 
{
  "buckets": [
    {
      object (EventCountTimelineBucket)
    }
  ],
  "size_of_bucket_ms": string
}
Fields
buckets[]

object (EventCountTimelineBucket)
size_of_bucket_ms

string (int64 format)

EventCountTimelineBucket

JSON representation 
{
  "baseline_event_count": integer,
  "event_count": integer,
  "baseline_alert_count": integer,
  "alert_count": integer,
  "baseline_timed_entity_count": integer,
  "filtered_timed_entity_count": integer,
  "entity_changed_count": {
    object (EntityChangedCountTimelineBucket)
  }
}
Fields
baseline_event_count

integer
event_count

integer
baseline_alert_count

integer
alert_count

integer
baseline_timed_entity_count

integer
filtered_timed_entity_count

integer
entity_changed_count

object (EntityChangedCountTimelineBucket)

EntityChangedCountTimelineBucket

JSON representation 
{
  "total_changed_entities_count": integer,
  "entity_changed_info": [
    {
      object (EntityChangedInfo)
    }
  ]
}
Fields
total_changed_entities_count

integer
entity_changed_info[]

object (EntityChangedInfo)

EntityChangedInfo

JSON representation 
{
  "artifacts": {
    object (FieldAndValue)
  },
  "entity_count": integer
}
Fields
artifacts

object (FieldAndValue)
entity_count

integer

FieldAndValue

JSON representation 
{
  "value": string,
  "entity_namespace": string,

  // Union field type can be only one of the following:
  "field_path": string,
  "kvalue_type": enum (KValueType)
  // End of list of possible types for union field type.
}
Fields
value

string
entity_namespace

string

Union field type.

type can be only one of the following:
field_path

string
kvalue_type

enum (KValueType)

KValueType

Enums
UNKNOWN
COLLECTOR_ID
EVENT_SHARD
ASSET_IP_ADDRESS
MAC
HOSTNAME
PRODUCT_SPECIFIC_ID
NAMESPACE
DOMAIN_NAME
RESOLVED_IP_ADDRESS
STEMMED_DOMAIN_NAME
PROCESS_ID
FULL_COMMAND_LINE
FILE_NAME
FILE_PATH
HASH_MD5
HASH_SHA256
HASH_SHA1
RAW_PID
PARENT_PROCESS_ID
EMAIL
USERNAME
WINDOWS_SID
EMPLOYEE_ID
PRODUCT_OBJECT_ID
USER_DISPLAY_NAME
CLOUD_RESOURCE_NAME
REGISTRY_KEY
REGISTRY_VALUE_DATA
REGISTRY_VALUE_NAME

UdmFieldAggregations

JSON representation 
{
  "fields": [
    {
      object (UdmFieldAggregation)
    }
  ],
  "group_by_fields": [
    {
      object (GroupAggregationByField)
    }
  ],
  "complete": boolean
}
Fields
fields[]

object (UdmFieldAggregation)
group_by_fields[]

object (GroupAggregationByField)
complete

boolean

UdmFieldAggregation

JSON representation 
{
  "field_name": string,
  "baseline_event_count": integer,
  "event_count": integer,
  "too_many_values": boolean,
  "value_count": integer,
  "all_values": [
    {
      object (UdmValueCount)
    }
  ],
  "top_values": [
    {
      object (UdmValueCount)
    }
  ],
  "bottom_values": [
    {
      object (UdmValueCount)
    }
  ],
  "aggregation_type": enum (UdmFieldAggregationType)
}
Fields
field_name

string
baseline_event_count

integer
event_count

integer
too_many_values

boolean
value_count

integer
all_values[]

object (UdmValueCount)
top_values[]

object (UdmValueCount)
bottom_values[]

object (UdmValueCount)
aggregation_type

enum (UdmFieldAggregationType)

UdmValueCount

JSON representation 
{
  "value": {
    object (UdmFieldValue)
  },
  "baseline_event_count": integer,
  "event_count": integer
}
Fields
value

object (UdmFieldValue)
baseline_event_count

integer
event_count

integer

UdmFieldValue

JSON representation 
{

  // Union field value can be only one of the following:
  "string_value": string,
  "int32_value": integer,
  "uint32_value": integer,
  "int64_value": string,
  "uint64_value": string,
  "float_value": number,
  "double_value": number,
  "enum_value": string,
  "bool_value": boolean,
  "bytes_value": string,
  "is_null": boolean,
  "timestamp_value": string
  // End of list of possible types for union field value.
}
Fields

Union field value.

value can be only one of the following:
string_value

string
int32_value

integer
uint32_value

integer (uint32 format)
int64_value

string (int64 format)
uint64_value

string
float_value

number
double_value

number
enum_value

string
bool_value

boolean
bytes_value

string (bytes format)

A base64-encoded string.
is_null

boolean
timestamp_value

string (Timestamp format)

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted.Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

UdmFieldAggregationType

Enums
UNSPECIFIED_FIELD_AGGREGATION_TYPE
UDM_FIELD_AGGREGATION_TYPE
ENTITY_FIELD_AGGREGATION_TYPE

GroupAggregationByField

JSON representation 
{
  "field_name": string,
  "field_value": {
    object (UdmFieldValue)
  },
  "fields": [
    {
      object (UdmFieldAggregation)
    }
  ],
  "baseline_event_count": integer,
  "event_count": integer,
  "value_count": integer
}
Fields
field_name

string
field_value

object (UdmFieldValue)
fields[]

object (UdmFieldAggregation)
baseline_event_count

integer
event_count

integer
value_count

integer

Detections

JSON representation 
{
  "detections": [
    {
      object (Collection)
    }
  ],
  "complete": boolean,
  "too_many_detections": boolean,
  "valid_snapshot_query": boolean,
  "baseline_alerts_count": integer,
  "filtered_alerts_count": integer,
  "detection_field_aggregations": {
    object (AlertFieldAggregations)
  }
}
Fields
detections[]

object (Collection)
complete

boolean
too_many_detections

boolean
valid_snapshot_query

boolean
baseline_alerts_count

integer
filtered_alerts_count

integer
detection_field_aggregations

object (AlertFieldAggregations)

FunctionResponse

JSON representation 
{
  "rows": [
    {
      object (FunctionResponseRow)
    }
  ],
  "too_many_rows": boolean
}
Fields
rows[]

object (FunctionResponseRow)
too_many_rows

boolean

FunctionResponseRow

JSON representation 
{
  "values": [
    {
      object (UdmFieldValue)
    }
  ]
}
Fields
values[]

object (UdmFieldValue)

UdmPrevalenceResponse

JSON representation 
{
  "buckets": [
    {
      object (UdmPrevalenceBucket)
    }
  ],
  "partial_prevalence": boolean
}
Fields
buckets[]

object (UdmPrevalenceBucket)
partial_prevalence

boolean

UdmPrevalenceBucket

JSON representation 
{
  "prevalence": [
    {
      object (UdmPrevalence)
    }
  ]
}
Fields
prevalence[]

object (UdmPrevalence)

UdmPrevalence

JSON representation 
{
  "artifacts": [
    {
      object (FieldAndValue)
    }
  ],
  "prevalence": integer
}
Fields
artifacts[]

object (FieldAndValue)
prevalence

integer

Stats

LINT.IfChange (stats_data) Stats results when the query is for statistics NEXT TAG = 6;

JSON representation 
{
  "results": [
    {
      object (ColumnData)
    }
  ],
  "data_query_expression": string,
  "too_many_results": boolean,
  "total_results": integer,
  "sort_order": [
    {
      object (ColumnSort)
    }
  ]
}
Fields
results[]

object (ColumnData)

Result rows that are queried.
data_query_expression

string

Expression that represent the subset of the requested query used to filter data. The expression will be used to enable features such as drill-down from stats results to UDM events. In that case, the new query will be composed by this expression and the expression related to a stats result.
too_many_results

boolean

If true, there are too many results to return and some have been omitted.
total_results

integer

The total number of results returned.
sort_order[]

object (ColumnSort)

Indicates the columns used for sorting and the order in which they are sorted. If no ORDER section is specified in the query, this will be empty.

ColumnData

Represents a single column in the set of columns returned as the stats query result.

JSON representation 
{
  "column": string,
  "values": [
    {
      object (ColumnType)
    }
  ],
  "filterable": boolean,
  "filter_expression": string
}
Fields
column

string

Used to store column names.
values[]

object (ColumnType)

To store store column data.
filterable

boolean

To identify if the column can be used for filtering/drill-downs.
filter_expression

string

Expression used to compose a query for filtering/drill-downs related to the data in this column.

ColumnType

Singular vs list of values in a column.

JSON representation 
{

  // Union field type can be only one of the following:
  "value": {
    object (ColumnValue)
  },
  "list": {
    object (List)
  }
  // End of list of possible types for union field type.
}
Fields

Union field type.

type can be only one of the following:
value

object (ColumnValue)

Single value in a column.
list

object (List)

List of values in a column e.g. IPs

ColumnValue

Value of the column based on data type

JSON representation 
{

  // Union field value can be only one of the following:
  "null_val": boolean,
  "bool_val": boolean,
  "bytes_val": string,
  "double_val": number,
  "int64_val": string,
  "uint64_val": string,
  "string_val": string,
  "timestamp_val": string,
  "date_val": {
    object (Date)
  },
  "proto_val": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field value.
}
Fields

Union field value.

value can be only one of the following:
null_val

boolean

True if the value is NULL.
bool_val

boolean

Boolean value.
bytes_val

string (bytes format)

Bytes value.

A base64-encoded string.
double_val

number

Double value.
int64_val

string (int64 format)

Integer value (signed).
uint64_val

string

Un-signed integer value.
string_val

string

String value. Enum values are returned as strings.
timestamp_val

string (Timestamp format)

Timestamp values.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted.Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
date_val

object (Date)

Date values.
proto_val

object

For any proto values that are not any of the above.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

List

Store list of values in a column.

JSON representation 
{
  "values": [
    {
      object (ColumnValue)
    }
  ]
}
Fields
values[]

object (ColumnValue)

List of values in one cell of the column.

ColumnSort

Contains the column name and which direction the column is sorted (ascending or descenging).

JSON representation 
{
  "name": string,
  "descending": boolean
}
Fields
name

string

Name of the column.
descending

boolean

Whether the column is sorted in descending order (ascending by default);

SearchDataSource

Data source for stats results in LegacyFetchUdmSearchViewResponse Equivalent to dashboard API LINT.IfChange(data_sources)

Enums
SEARCH_DATA_SOURCE_UNSPECIFIED Unspecified data source.
SEARCH_UDM Events
SEARCH_ENTITY Entities
SEARCH_RULE_DETECTIONS To be used for detections data source.
SEARCH_RULESETS To be used for ruleset with detections datasource.

AIOverview

AI generated overview for the search results.

JSON representation 
{
  "ai_summary": string,
  "suggestions": [
    {
      object (Action)
    }
  ],
  "complete": boolean
}
Fields
ai_summary

string

AI summary for the search results. Markdown formatted.
suggestions[]

object (Action)

Suggested actions to continue the investigation in chat.
complete

boolean

Whether AI overview generation is complete.