Query Syntax

A query is a list of clauses separated by whitespace. Every clause must match, so timeout db finds logs containing both words. Clauses are either free text (matched against the log message) or key:value field filters.

The logs explorer highlights the query as you type, underlines the offending token when something is wrong, and autocompletes field names and values. An explicit AND between two clauses is accepted and means the same as whitespace.

• Word - a run of letters, digits and underscores, such as timeout or user_id. It matches whole words in the message, ignoring case. time does not match timeout.
• Phrase - text in double quotes. It matches anywhere in the message as a case-insensitive substring. Use \" for a quote and \\ for a backslash inside a phrase.
• Anything else is a phrase too. A term containing punctuation, such as 10:42:13, http://example.com/health, 10.0.0.5, Error: or an IPv6 address, is searched as plain text, so you can paste a log line fragment straight into the search bar.

Numbers and booleans compare by their text, so status:500 and ok:false work as you would expect. Arrays and objects have no text form and never match an equals, in or contains clause. Excluding a contains match (-path:*admin*) is not supported and is reported as an error.

Put - directly in front of a word, phrase or field clause to exclude it. A negated clause matches logs that do not have the key at all. For example -env:prod returns staging logs and logs that carry no env field. To require the key and exclude one value, combine the two clauses:

env:* -env:prod

OR (uppercase) joins the two terms next to it into an any-of group. Groups are AND-ed with the rest of the query, so timeout OR refused db means (timeout OR refused) AND db. There are no nested parentheses.

• Between free-text terms: timeout OR "connection reset".
• Between values of one field: env:prod OR env:staging is the same as env:(prod OR staging).
• OR between clauses of different fields (service:api OR level:error) is an error with a hint. Run two searches, or use a list on a single field.
• OR cannot join excluded terms (-a OR -b).
• Parentheses are only valid as a value list after a key, like key:(a OR b). Quote text that contains parentheses.

Any other operator on a built-in field (service:*api*, level:*, -trace:abc) is a parse error, so the search bar, the API and live tail always agree. Each built-in can appear once as a positive filter; use a list (service:(api OR worker)) for several values. Key names are case-sensitive.

Any other key filters on the log's metadata. Nested objects are reached with dots: user.id:42 finds {"user": {"id": 42}}. If a log has a metadata key that literally contains a dot, such as http.status_code, the exact key wins over the nested path. Paths never index into arrays.

env:(prod OR staging)
user.id:*
-region:eu-west-1
http.status_code:500
path:*admin*

The logs explorer discovers metadata keys from recent logs and offers them as autocomplete suggestions and facets. Clicking a value in the details panel adds or removes the matching clause in the query text, so the query bar is always the full description of the current view.

Time and project are not part of the query text. They are set by the scope bar at the top of every explore page and carried in the page URL, so a shared link opens with the same scope:

Through the API, pass projectId, from and to as query parameters next to q. The last used scope is remembered per browser.

Only genuinely malformed input is rejected: an unclosed quote or parenthesis, an OR without a term on both sides, an OR between different fields, an unknown level value, or an operator a built-in field does not support. Each error carries the character position of the problem. The UI underlines that token, and the API answers HTTP 400. For service:api OR level:error the response is:

{
  "error": "OR can only join free-text terms, or values of the same field; use key:(a OR b)",
  "position": 12
}

The query goes in the q parameter. It is accepted by the same endpoints, with the same authentication as GET /api/v1/logs:

curl -G http://localhost:8080/api/v1/logs \
  -H "X-API-Key: lp_your_api_key" \
  --data-urlencode 'projectId=PROJECT_UUID' \
  --data-urlencode 'from=2026-10-30T08:00:00Z' \
  --data-urlencode 'to=2026-10-30T09:00:00Z' \
  --data-urlencode 'q=level:(error OR critical) "connection refused" -host:web-1'

Legacy parameters. searchMode=substring treats the whole q as one phrase, as before. searchMode=fulltext or no searchMode parses q with this grammar, so existing callers keep working. Alert rules accept the same syntax in their query field (threshold rules only); an invalid query is rejected with HTTP 400 and a position.

Numeric comparisons (status:>=500) and nested parentheses are not supported.

The grammar, the field rules and the handling of missing keys are identical on all three engines and pinned by a shared conformance suite. The differences are in how free-text words are looked up:

English stemming on TimescaleDB is the one documented difference. Quoted phrases are never stemmed. See Storage Engines for engine requirements.