Query filter reference

Table of Contents

For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. Append .md to any kestra.io/docs/* URL for plain Markdown.

Available on:Open Source Edition Enterprise Edition Cloud

Kestra list and bulk by-query endpoints accept structured filters via the filters query parameter. This page covers the syntax, available operators, and the fields that flows, executions, and triggers support. Other resources, such as logs, namespaces, KV entries, and secrets, also accept filters with their own fields.

Syntax

Filters use bracket notation: filters[<field>][<operator>]=<value>.

GET /api/v1/main/executions/search?filters[namespace][EQUALS]=company.team

Pass multiple filters as separate query parameters:

GET /api/v1/main/executions/search?filters[namespace][EQUALS]=company.team&filters[state][IN]=CREATED,RUNNING

AND / OR grouping

Logical groups use the same bracket notation as top-level filters, wrapped under or[N] or and[N]. Each index N is one branch of the group, and filters that share the same index are combined with AND:

GET /api/v1/main/flows/search
  ?filters[or][0][namespace][EQUALS]=company.docs
  &filters[or][0][flowId][STARTS_WITH]=report
  &filters[or][1][namespace][EQUALS]=company.test

This returns flows in company.docs whose ID starts with report, plus every flow in company.test. Groups can be nested, for example filters[and][0][or][0][...]. Ungrouped top-level filters are combined with AND.

Filter on labels

Put the label key in a third bracket and the label value after =:

GET /api/v1/main/executions/search?filters[labels][EQUALS][env]=prod

A value written as key:value, such as filters[labels][EQUALS]=env:prod, is rejected with an invalid-query-filters error. Only CONTAINS, NOT_CONTAINS, IS_NULL, and IS_NOT_NULL accept a value without a key: CONTAINS and NOT_CONTAINS match the text in any label key or value, and IS_NULL and IS_NOT_NULL take a label key.

Several keys under the same operator are combined with AND, so filters[labels][EQUALS][env]=prod&filters[labels][EQUALS][team]=data matches executions that have both labels. Under IN, matching any one of the key and value pairs is enough.

Limits

A filter can nest groups up to 3 levels deep, and each group can hold up to 20 filters or groups. A request that exceeds either limit is rejected with an invalid-query-filters error. Raise the limits with kestra.webserver.query-filter.max-depth and kestra.webserver.query-filter.max-width. Values below the defaults are raised to the defaults.

Operators

Operator	Description
`EQUALS`	Exact match
`NOT_EQUALS`	Excludes exact match
`IN`	Matches any value in a comma-separated list: `filters[state][IN]=CREATED,RUNNING`
`NOT_IN`	Excludes all values in a comma-separated list
`CONTAINS`	Value contains the string
`NOT_CONTAINS`	Value does not contain the string
`STARTS_WITH`	Value starts with the string
`ENDS_WITH`	Value ends with the string
`PREFIX`	Dot-segment prefix match — `company` matches `company`, `company.team`, and `company.team.prod`, but `company.t` does not match `company.team`. Primarily useful on `namespace` and `flowId` fields that use dot notation.
`REGEX`	Regular expression match. The dialect depends on the backend database or Elasticsearch. Patterns longer than 250 characters or prone to catastrophic backtracking are rejected.
`GREATER_THAN`	Value is greater than (for dates and numbers)
`LESS_THAN`	Value is less than
`GREATER_THAN_OR_EQUAL_TO`	Value is greater than or equal to
`LESS_THAN_OR_EQUAL_TO`	Value is less than or equal to
`IS_NULL`	Field is absent or null (no value needed)
`IS_NOT_NULL`	Field is present and not null (no value needed)

Not every operator applies to every field. The per-resource tables below list only the operators each field actually supports.

Fields by resource

Flows

Field	Operators	Notes
`namespace`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `REGEX`, `IN`, `NOT_IN`, `PREFIX`
`flowId`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `REGEX`, `IN`, `NOT_IN`, `PREFIX`	`PREFIX` matches dot-segment boundaries only
`labels`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`, `CONTAINS`, `NOT_CONTAINS`, `IS_NULL`, `IS_NOT_NULL`	Key in a third bracket: `filters[labels][EQUALS][env]=prod`. See Filter on labels.
`scope`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`	Values: `USER`, `SYSTEM`
`q`	`EQUALS`, `NOT_EQUALS`	Full-text search across flow id and namespace

Executions

Field	Operators	Notes
`namespace`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `REGEX`, `IN`, `NOT_IN`, `PREFIX`
`flowId`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `REGEX`, `IN`, `NOT_IN`, `PREFIX`	`PREFIX` matches dot-segment boundaries only
`state`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`	Values: `CREATED`, `SUBMITTED`, `RUNNING`, `PAUSED`, `RESTARTED`, `KILLING`, `SUCCESS`, `WARNING`, `FAILED`, `KILLED`, `CANCELLED`, `QUEUED`, `RETRYING`, `RETRIED`, `SKIPPED`, `BREAKPOINT`, `RESUBMITTED`
`labels`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`, `CONTAINS`, `NOT_CONTAINS`, `IS_NULL`, `IS_NOT_NULL`	Key in a third bracket: `filters[labels][EQUALS][env]=prod`. See Filter on labels.
`startDate`	`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`	ISO 8601 format: `2024-01-01T00:00:00Z`
`endDate`	`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`	ISO 8601 format: `2024-01-01T00:00:00Z`
`scope`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`	Values: `USER`, `SYSTEM`
`kind`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`	Values: `NORMAL`, `TEST`, `PLAYGROUND`, `LOOP`
`childFilter`	`EQUALS`, `NOT_EQUALS`	Values: `CHILD`, `MAIN`
`parentId`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`	Execution ID of the parent execution
`taskId`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `IN`, `NOT_IN`
`triggerId`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `IN`, `NOT_IN`
`triggerExecutionId`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `IN`, `NOT_IN`
`q`	`EQUALS`, `NOT_EQUALS`	Full-text search across execution id, flow id, and namespace

Triggers

Field	Operators	Notes
`namespace`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `REGEX`, `IN`, `NOT_IN`, `PREFIX`
`flowId`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `REGEX`, `IN`, `NOT_IN`, `PREFIX`	`PREFIX` matches dot-segment boundaries only
`triggerId`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `IN`, `NOT_IN`
`triggerState`	`EQUALS`, `NOT_EQUALS`	Values: `disabled`, `enabled`
`scope`	`EQUALS`, `NOT_EQUALS`, `IN`, `NOT_IN`	Values: `USER`, `SYSTEM`
`workerId`	`EQUALS`, `NOT_EQUALS`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `IN`, `NOT_IN`
`source`	`EQUALS`	Values: `SCHEDULE`, `POLLING`, `REALTIME`
`locked`	`EQUALS`	Values: `true`, `false`
`lastTriggeredDate`	`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`	ISO 8601 format: `2024-01-01T00:00:00Z`
`nextExecutionDate`	`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`	ISO 8601 format: `2024-01-01T00:00:00Z`
`q`	`EQUALS`, `NOT_EQUALS`	Full-text search across trigger id, flow id, and namespace

Mutating by-query endpoints

Bulk endpoints (DELETE, POST, and PUT on .../by-query paths) require the filters[...] form. Flat legacy parameters such as ?namespace=x are rejected with a 400 invalid-query-filters error.

Read-only exports (GET .../export/by-query) are not subject to this restriction.

See Invalid query filters for the full error reference and migration examples.

SDKsSDK Language Clients for the Kestra API

Was this page helpful?