Filter Expressions

RelayCore shares one filter expression across multiple surfaces:

The / bar in the TUI
relay-core-cli flows --filter on the CLI
Structured query parameters on GET /api/v1/flows
The filter field of the search_flows MCP tool

All of these are interpreted by the same parser. Master the syntax once and use it everywhere.

Basic syntax

An expression is a space-separated list of tokens. Multiple tokens are AND-combined. Bare tokens substring-match the URL + method (case-insensitive).

# Substring match against host
host:api
host:api.example.com

# Substring match against path
path:/v1/users
path:/graphql

# HTTP method (case-insensitive)
method:GET
method:POST

# Status code (exact, range, or comparison)
status:404
status:400-499
status:>=500
status:<300

# Flow-level flags
err         # any flow with has_error == true (alias: error)
ws          # WebSocket flows (alias: websocket)

# Plain text substring (matched against the joined URL + method)
health
users

Combining tokens

Multiple tokens are implicit AND:

# Failed POSTs to api host
host:api method:POST status:>=400

# 5xx WebSocket errors
ws status:500-599

# Any 2xx containing health
health status:<300

Status code syntax

Status codes support four forms:

Form	Meaning	Example
Exact	Equality	`status:404`
Range	Closed interval	`status:400-499`
Lower bound	`>=` or `>`	`status:>=500`
Upper bound	`<=` or `<`	`status:<300`

No space is allowed between the operator and the number.

HTTP API structured parameters

When using GET /api/v1/flows, the structured-parameter equivalents are:

Token	Query parameter
`host:api`	`?host=api`
`path:/v1/users`	`?path=/v1/users`
`method:POST`	`?method=POST`
`status:>=500`	`?status_min=500`
`status:<300`	`?status_max=299`
`status:400-499`	`?status_min=400&status_max=499`
`err`	`?has_error=true`
`ws`	`?is_websocket=true`

Structured parameters are clearer for simple lookups; the token form is shorter for ad-hoc debugging.

Case & substring semantics

All string fields are matched case-insensitively.
host and path are substring matches, not globs. To match api.example.com you write the full substring, not api.*.com.
Method is exact match (case-insensitive) against the standard methods (GET / POST / PUT / DELETE / PATCH / HEAD / OPTIONS) plus WS.
Bare tokens match against the joined "URL + method" string, so health hits any flow whose URL contains "health" (in practice that's the only case).

Common pitfalls

Bare tokens match too much: api matches any flow with "api" in the host, path, or URL. Add a host: / path: prefix to disambiguate.
Spaces around operators: status:> 500 is invalid; use status:>=500.
Cross-surface semantics differ: the TUI applies the filter live; the CLI returns a single page; the HTTP API returns paginated results. Same syntax, different interaction.