Invalid query filters

The filters on a list endpoint could not be parsed, or they reference something that cannot be filtered on.

• HTTP status — 400 Bad Request
• type — https://kestra.io/docs/api-reference/problems/invalid-query-filters

When you get it

• The filters[...] syntax is malformed.
• The field is one the endpoint does not support filtering on.
• The operator does not apply to that field’s type.
• A mutating by-query endpoint (DELETE, POST, or PUT on a .../by-query path) received a filter as a flat query parameter, such as ?namespace=x, instead of the filters[...] form.

Since Kestra 2.0.7, the last case applies to bulk endpoints for executions, flows, and triggers (delete, kill, restart, replay, change-status, labels, pause/resume, unqueue, force-run, enable/disable, and similar). Read-only exports (GET .../export/by-query) are not affected. Before 2.0.7, these endpoints silently dropped flat parameters, so a call such as DELETE /api/v1/main/flows/delete/by-query?namespace=x ran with no filter and deleted every flow in the tenant, not only those in x. Review any scripts that call by-query endpoints with flat parameters.

Example responses

A response for a malformed or unsupported filter field:

{
  "type": "https://kestra.io/docs/api-reference/problems/invalid-query-filters",
  "title": "Invalid query filters",
  "status": 400,
  "detail": "Unknown filter field 'stat'.",
  "instance": "/api/v1/main/executions/search"
}

A response for a legacy flat parameter on a mutating by-query endpoint:

{
  "type": "https://kestra.io/docs/api-reference/problems/invalid-query-filters",
  "title": "Invalid query filters",
  "status": 400,
  "detail": "'namespace' is not a supported query parameter on this endpoint, use filters[namespace][EQUALS]=<value>",
  "instance": "/api/v1/main/flows/delete/by-query"
}

How to handle it

Check the field and the operator against the filters the endpoint documents. An unrecognised filter is rejected rather than ignored, so that a query never silently returns unfiltered results.

For the flat-parameter case, rewrite the call to use the filters[<field>][<op>]=<value> form. For example:

# Legacy form: rejected on mutating by-query endpoints
DELETE /api/v1/main/executions/delete/by-query?namespace=company.team

# Correct form
DELETE /api/v1/main/executions/delete/by-query?filters[namespace][EQUALS]=company.team

Multiple filters are passed as separate query parameters:

DELETE /api/v1/main/executions/delete/by-query?filters[namespace][EQUALS]=company.team&filters[flowId][EQUALS]=my_flow

For the full list of available fields and operators per resource type, see Query filter reference.

For the members every problem document carries, see Problem Details.