Query branch logs

post

https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/logs/query

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.

Path Params

project_id

string

required

^[a-z0-9-]{1,60}$

The Neon project ID

branch_id

string

required

^[a-z0-9-]{1,60}$

The Neon branch ID

Body Params

since

string

^[0-9]{1,6}(ms|s|m|h|d)$

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_time

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_time

date-time

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

limit

integer

1 to 1000

Defaults to 100

Maximum number of log records to return per page.

cursor

string

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

string

enum

Defaults to desc

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

Allowed:

source

string

enum

The Neon service that emitted the log record.

Allowed:

service_name

string

length ≥ 1

Match the OpenTelemetry service.name resource attribute exactly.

scope_name

string

length ≥ 1

Match the OpenTelemetry instrumentation scope name exactly.

minimum_severity

string

enum

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

Allowed:

severity_text

string

length ≥ 1

Match the OpenTelemetry severity text exactly.

body_contains

string

length ≥ 1

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_id

string

^[0-9a-f]{32}$

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.

logql

string

length ≥ 1

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.

Responses

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Logs matching the supplied filters

400The query could not be served as written. The body is always ProjectBranchLogsInvalidQuery — see reason for the exact cause.

404Logs are not available for this branch, or the project/branch was not found. The body is always ProjectBranchLogsNotAvailable — see reason for the exact cause.