Work with list operations

Supported in:

Google secops SIEM SOAR

Chronicle REST API endpoints that return lists of resources often support parameters for filtering, ordering, and pagination. These parameters, typically filter, orderBy, and pageSize, follow standard Google Cloud API conventions.

Note: The filtering, ordering, and pagination options detailed in this guide apply primarily to SOAR and incident response endpoints. Other list methods across the Chronicle API might not support the full range of filtering parameters or syntax.

Filter results

Use the filter parameter to narrow the returned list of resources based on specific criteria. The following sections describe the supported operators, functions, and formatting requirements for constructing filter expressions.

Comparison operators

You can compare a specific resource field against a constant value using the following comparison operators:

Operator	Description
>	Greater than
>=	Greater than or equal to
<	Less than
<=	Less than or equal to
=	Equal to
!=	Not equal to
:	Has (checks for exact substring matching or membership)
in	In a list of values (for example, id in (1, 2, 3))

Logical operators

Combine multiple comparison conditions or negate specific criteria using the following logical operators:

Operator	Description
and / AND	Logical AND
or / OR	Logical OR
not / NOT / -	Logical NOT or unary minus

Collection and string functions

Use built-in functions to evaluate text properties, repeated fields, and collections dynamically across resource items:

Function	Description
any(collection, condition)	Checks whether any element in a collection matches a condition
anyContains(collection, substring)	Checks whether any element in a collection contains the specified substring
anyEndswith(collection, substring)	Checks whether any element in a collection ends with the specified substring
anyEquals(collection, substring)	Checks whether any element in a collection equals the specified value
anyStartswith(collection, substring)	Checks whether any element in a collection starts with the specified substring
contains(string, match)	Checks whether a string contains the specified substring
startswith(string, match)	Checks whether a string starts with the specified substring
endswith(string, match)	Checks whether a string ends with the specified substring

For detailed examples demonstrating how to apply these functions across repeated fields and collections, see Examples of complex filtering across repeated fields and collections.

Date and null filters

Rule category	Formatting requirement	Example filter snippet
Null checks	To check whether a field is unassigned or null, use the literal null keyword	middleName = null
Date formatting	Format all timestamp and date fields using the international standard ISO 8601 format (YYYY-MM-DDThh:mm:ssZ)	createTime >= '2026-01-01T00:00:00Z'

Wildcards and special characters

Rule category	Formatting requirement	Example filter snippet
Wildcard matches	Use the asterisk (*) wildcard within string comparisons to match zero or more characters	displayName = '*CreateCase*'
Special character escaping	Escape special characters, such as double quotes, within filter strings using a backslash (\)	filter=displayName="My Case Title with \"Quotes\""

Filter query examples

The following table demonstrates how to construct simple and advanced URI filter strings using comparison operators, logical operators, and functions.

Query complexity	Filter target	Example URI query string
Simple	Cases by exact status	/cases?filter=status='OPENED'
Simple	Announcements after a specific update time	/announcements?filter=updateTime > 1783943356995
Advanced	Tasks by status and multiple possible assignees	/tasks?filter=status="PENDING" and (assignee="d485b3ab-b9da-40a5-9a79-58e81b51c06e" or assignee="@Administrator")
Advanced	Marketplace integrations matching a category substring	/marketplaceIntegrations?filter=anyContains(categories, 'Threat Intelligence')

Filter examples for common attributes

The following table demonstrates how to construct filter query strings for common case attributes, grouped by filter category.

Filter category	Case attribute	Example filter query
Numeric	Case ID (numeric lookup)	filter=id=12345
String	Display name (case title, supports wildcards)	filter=displayName='*CreateCase*'
String	Assignee (username, role, or queue)	filter=assignee='*@Tier1*'
String	Case description	filter=description='*Brute force attack detected*'
String	Environment	filter=environment='*Default Environment*'
String	Case stage	filter=stage='*Triage*'
Enum	Case status	filter=status='OPENED'
Enum	Case priority	filter=priority='HIGH'
Enum	Workflow status	filter=workflowStatus='IN_PROGRESS'
Boolean	Important flag (important)	filter=important=true
Boolean	Incident flag (incident)	filter=incident=false

Examples of complex filtering across repeated fields and collections

Use functions such as any and anyContains to construct complex filter queries across repeated fields and collections.

Note: When filtering on the tags field, pass expand=tags in your request to populate the full tag objects in the returned resources.

Target collection	Filter description	Example filter query
Tags (tags)	Find cases that contain a specific exact tag	expand=tags filter=(any(tags.displayName, 'Phishing'))
Tags (tags)	Find cases matching a tag substring	expand=tags filter=(anyContains(tags.displayName, 'Phishing'))
Tags (tags)	Find cases matching any exact tag from a list of values	expand=tags filter=(any(tags.displayName, 'Toxic Combination', 'False Positive'))
Products (products)	Find cases matching a product substring across associated products	filter=(anyContains(products.displayName, 'SentinelOne'))
Alerts (alertNames)	Find cases matching an alert name substring	filter=(anyContains(alertNames.alertName, 'Suspicious Login'))
Alerts (alertNames)	Find cases matching any exact alert name from a list of values	filter=(any(alertNames.alertName, 'PHISHING_EML', 'SUSPICIOUS_EXEC'))
Custom fields (customFieldValues)	Find cases matching a substring across all custom field search text	filter=(anyContains(customFieldValues.valuesSearchText, 'Arkansas'))

Order results

Use the orderBy parameter to sort the returned list of resources.

• Field names: Specify the field to sort by.
• Sort direction: Append desc for descending order or asc for ascending order (asc is the default).
• Multiple fields: Sort by multiple fields by providing a comma-separated list.

The following table demonstrates how to construct ordering parameter strings (orderBy) for common case queries.

Sort criteria	Ordering description	Example order string
Single field (updateTime)	Sort cases by their last update time in descending order	orderBy="updateTime desc"
Multiple fields (priority, updateTime)	Sort cases by priority in ascending order, then by update time in descending order	orderBy="priority asc, updateTime desc"

Paginate results

Use the pageSize and pageToken parameters to paginate results for endpoints that return large datasets.

Parameter	Description
pageSize	Specifies the maximum number of resources to return in a single response. If you don't specify pageSize, the API uses a default page size.
pageToken	A token received in a previous response's nextPageToken field. Provide this to retrieve the subsequent page of results.

To paginate results, do the following:

1. Make an initial request, optionally specifying pageSize.
2. If the response includes a nextPageToken, there are more results.
3. Make a subsequent request, including the received nextPageToken in the pageToken parameter to get the next page.
4. Repeat until the server no longer returns nextPageToken.

Pagination example

The following example demonstrates how to paginate cases using curl:

# Initial request
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://chronicle.googleapis.com/v1/projects/PROJECT/locations/LOCATION/instances/INSTANCE/cases?pageSize=10"

# Sample response might include:
# {
#   "cases": [...],
#   "nextPageToken": "A_B_C_D_E_F"
# }

# Request for the next page
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://chronicle.googleapis.com/v1/projects/PROJECT/locations/LOCATION/instances/INSTANCE/cases?pageSize=10&pageToken=A_B_C_D_E_F"

Best practices

Best practice	Guidance
Consult the API reference	Refer to the specific REST API documentation for your endpoint (for example, projects.locations.instances.cases/list) to verify supported fields and syntax.
Test filters incrementally	Start with basic filters and gradually add complexity.
URL-encode parameters	Make sure parameter values are properly URL-encoded in your requests.
Handle errors	Account for potential errors from invalid filter syntax.

Need more help? Get answers from Community members and Google SecOps professionals.