Sign in
Logs

Query branch logs

Changed on

Returns logs emitted by services running on the specified branch, ordered by timestamp according to sort_order.

All supplied filters are combined with AND: a record is returned only when it matches every filter. minimum_severity and severity_text are independent filters, so setting both requires a record to clear the severity floor and match the exact severity text.

Supply logql instead of the structured filters to run a raw LogQL expression. Combining it with any structured filter is rejected rather than silently ignored; limit, sort_order, and the time window still apply, because those bound the query rather than form part of the expression.

Give the window either as since — a duration ending at end_time, or at the current time when end_time is omitted — or as an explicit start_time. Supplying both is rejected.

A single response holds at most 1,000 records. When is_truncated is true, pass the returned next_cursor back as cursor to fetch the next page, repeating the time range and every filter unchanged.

If no time range is supplied, the query covers the previous hour. The maximum supported time range is seven days. end_time is exclusive.

Note: This endpoint is currently in Private Beta.

post/projects/{project_id}/branches/{branch_id}/logs/query

Request

  • Base URL: https://console.neon.tech/api/v2
  • URL: https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/logs/query
  • Auth: one of:
    • HTTP bearer
    • API key in cookie zenith
    • API key in cookie keycloak_token

Request body

sincestring

A length of time as a count and a unit, for example 30m, 6h, or 7d. Valid units are ms, s, m, h, and d.

start_timestring date-time

Inclusive beginning of the query window. Mutually exclusive with since. Defaults to one hour before end_time, or one hour before the current time when both bounds are omitted.

end_timestring date-time

Exclusive end of the query window. Defaults to the current time.

limitinteger

Maximum number of log records to return per page.

cursorstring

Opaque pagination cursor returned as next_cursor by a previous call. Resume the query after the last record of the previous page, repeating the time range and every filter unchanged.

sort_order'asc' | 'desc'

Order matching records by timestamp. desc, the default, returns the newest records first.

source'function' | 'storage' | 'pg_endpoint'

The Neon service that emitted the log record.

service_namestring

Match the OpenTelemetry service.name resource attribute exactly.

scope_namestring

Match the OpenTelemetry instrumentation scope name exactly.

minimum_severity'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'

An OpenTelemetry severity level. A minimum severity includes every higher level in this order: trace, debug, info, warn, error, fatal.

severity_textstring

Match the OpenTelemetry severity text exactly.

body_containsstring

Match records whose rendered message contains this case-sensitive substring.

Records with a structured body are matched against their JSON rendering, so the substring meets JSON syntax rather than prose: a bare key name such as operation matches every record carrying that key, and http_status: 200 matches none, because the rendering contains "http_status":200 with no space.

trace_idstring

Match records associated with this OpenTelemetry trace ID. W3C Trace Context defines a trace ID as 32 lowercase hex digits, and that is what is stored, so an uppercase value is rejected rather than silently matching nothing.

logqlstring

Escape hatch for selections the structured filters cannot express: a raw LogQL expression, evaluated against this branch's log stream.

Only stream selectors and line filters are accepted — no aggregations and no parser stages. Supplying this alongside any structured filter is rejected with conflicting_filters rather than silently ignoring one of them. limit, sort_order, and the time window still apply.

This field passes the underlying query language through to the caller, so unlike the rest of this contract it may change as that backend changes. Prefer the structured filters where they suffice.

Example request

{
  "since": "1h",
  "logql": "{entity_type=\"function\"} |~ \"(?i)timeout\""
}

Response

Logs matching the supplied filters

next_cursorstring

Pagination cursor to pass as cursor on the next request. Empty when the response is not truncated.

is_truncatedboolean required

True when more records matched than were returned.

Changes