Utila’s API methods that retrieve collections (e.g. ListTransactions, QueryBalances) support a powerful, flexible filtering system based on the Google AIP‑160 standard. Filters let clients limit results using a familiar and intuitive syntax which includes logical operators, comparison operation, custom functions and more.

General Usage and Syntax Overview

Single filter field:
- An endpoint which supports filtering include exactly one filter string field (query parameter) in the request in which the filter string should be supplied.
  - When the filter field is supplied twice, the latter will apply.
Literals:
- Bare values (e.g. 42, "foo") match anywhere unless restricted.
- Multiple bare literals imply AND (e.g. foo bar ≈ foo AND bar).
Logical operators:
- AND, OR (OR binds tighter than AND).
- Precedence: a AND b OR c ≡ a AND (b OR c).
- Best practice: use parentheses to clarify.
Negation:
- Supported via NOT a or -a.
Comparison operators:
- =, !=, <, >, <=, >= for numeric, string, timestamp.
- Left-hand side must be a field; right-hand side is a literal.
Functions:
- Most of the filters in Utila are exposed as functions.
- The supported functions for each endpoint are documented.

Example Filters in Utila

GET /v2/vaults/{vault_id}/transactions?filter=state(AWAITING_SIGNATURE) AND create_time >= "2025-01-01T00:00:00Z"

Returns transactions which are awaiting signature and were created in 2025 or later.

GET /v2/vaults/{vault_id}/transactions?filter=state(AWAITING_SIGNATURE) AND create_time >= "2025-01-01T00:00:00Z"

Returns transactions which are awaiting approval by the user with email me@example.com or the service account which invoked the query

GET /v2/vaults/{vault_id}/transactions?filter=pending_user_approval('users/me@example.com') OR pending_user_approval('users/me')

Returns the vault balance of Ethereum's native asset.

GET /v1/vaults/{vault_id}/transactions?filter=from\_wallet("vaults/c3b45307702d/wallets/02622144f54e") AND state(AWAITING\_SIGNATURE)

Returns transactions which are awaiting signature by wallet vaults/c3b45307702d/wallets/02622144f54e

Endpoint-Specific Behavior

Each endpoint defines which functions are supported for filtering. For example, ListTransactions allows:

Function	Type	Examples
`create_time`	string	`create_time > "2025-01-01T00:00:00Z"`
`state`	function(enum...)	`state(AWAITING_APPROVAL, AWAITING_SIGNATURE)`
`spam`	function(bool)	`spam(false)`