Skip to main content
Neon Postgres Docs

Search documentation

Type to search this documentation.

Query branch logs

POST/projects/{project_id}/branches/{branch_id}/logs/queryQuery branch logs

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.

Parameters

project_idstringpathrequired

The Neon project ID

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

branch_idstringpathrequired

The Neon branch ID

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

Request body

required
application/json
objectProjectBranchLogsQueryRequest
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.

minLength 1

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.

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.

default 100 · maximum 1000 · minimum 1

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.

minLength 1

minimum_severitystring

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

one of "trace", "debug", "info", "warn", "error", "fatal"

scope_namestring

Match the OpenTelemetry instrumentation scope name exactly.

minLength 1

service_namestring

Match the OpenTelemetry `service.name` resource attribute exactly.

minLength 1

severity_textstring

Match the OpenTelemetry severity text exactly.

minLength 1

sincevalue

Length of the query window, ending at `end_time` or at the current time when `end_time` is omitted. Mutually exclusive with `start_time`. Prefer this over computing absolute bounds when the caller only means "the last hour".

Show child attributes
allOf · 1 option
Option 1stringProjectBranchLogDuration

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`.

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

sort_orderstring

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

one of "asc", "desc" · default "desc"

sourcestring

The Neon service that emitted the log record.

one of "function", "storage", "pg_endpoint"

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.

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.

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

Example request
{
  "body_contains": "string",
  "cursor": "string",
  "end_time": "2026-06-09T00:00:00Z",
  "limit": 100,
  "logql": "{entity_type=\"function\"} |~ \"(?i)timeout\"",
  "minimum_severity": "debug",
  "scope_name": "string",
  "service_name": "string",
  "severity_text": "string",
  "since": "1h",
  "sort_order": "desc",
  "source": "function",
  "start_time": "2026-06-09T00:00:00Z",
  "trace_id": "string"
}

Responses

200Logs matching the supplied filtersapplication/json
objectProjectBranchLogsQueryResponse
is_truncatedbooleanrequired

True when more records matched than were returned.

logsarray of objectrequired
Show child attributes
Show array items
attributesobjectrequired

Customer-defined OpenTelemetry log and resource attributes.

entity_idstring

The Neon identifier of the service instance that emitted the record.

messagestringrequired

The OpenTelemetry log body rendered as text. A body that is already a string is returned verbatim. Any other OpenTelemetry `AnyValue` body — notably the structured key/value body that `storage` records always carry — is rendered as compact JSON with its keys sorted alphabetically, for example `{"bytes":1024,"operation":"GET","object_key":"a/b.png"}`.

scope_namestring

The OpenTelemetry instrumentation scope name.

service_namestring

The OpenTelemetry `service.name` resource attribute.

severity_numberinteger

The numeric OpenTelemetry severity.

maximum 24 · minimum 0

severity_textstring

The original OpenTelemetry severity text.

sourcestring

The Neon service that emitted the log record.

one of "function", "storage", "pg_endpoint"

span_idstring

The OpenTelemetry span ID, when the record belongs to a span.

timestampstring · date-timerequired

The OpenTelemetry record timestamp in UTC.

trace_idstring

The OpenTelemetry trace ID, when the record belongs to a trace.

next_cursorstring

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

Example response
{
  "is_truncated": true,
  "logs": [
    {
      "attributes": {
        "additionalProp1": null
      },
      "entity_id": "string",
      "message": "string",
      "scope_name": "string",
      "service_name": "string",
      "severity_number": 0,
      "severity_text": "string",
      "source": "function",
      "span_id": "string",
      "timestamp": "2026-06-09T00:00:00Z",
      "trace_id": "string"
    }
  ],
  "next_cursor": "string"
}
400The query could not be served as written. The body is always `ProjectBranchLogsInvalidQuery` — see `reason` for the exact cause. application/json
objectProjectBranchLogsInvalidQuery
codestringrequired
messagestringrequired
reasonstringrequired

Machine-readable reason why the request was rejected: - `time_range_too_large`: the requested window spans more than seven days. - `invalid_time_range`: `end_time` is not after `start_time`. - `conflicting_time_range`: both `since` and `start_time` were supplied. - `invalid_cursor`: the supplied `cursor` is malformed, expired, or was issued for a different query. - `unknown_field`: the requested `field_name` is not one of the fields the log fields endpoint reports for this branch. - `invalid_logql`: the supplied `logql` expression does not parse, or uses a construct this endpoint does not accept. - `conflicting_filters`: `logql` was supplied alongside one or more structured filters. Use one or the other.

one of "time_range_too_large", "invalid_time_range", "conflicting_time_range", "invalid_cursor", "unknown_field", "invalid_logql", "conflicting_filters"

Example response
{
  "code": "LOGS_INVALID_QUERY",
  "message": "string",
  "reason": "conflicting_filters"
}
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. application/json
objectProjectBranchLogsNotAvailable
codestringrequired
messagestringrequired
reasonstringrequired

Machine-readable reason why logs cannot be read: - `branch_not_found`: the project or branch does not exist, or the caller does not have access to it. - `telemetry_not_enabled`: the branch exists but is not collecting telemetry, so it has no logs to serve.

one of "branch_not_found", "telemetry_not_enabled"

Example response
{
  "code": "LOGS_NOT_AVAILABLE",
  "message": "string",
  "reason": "branch_not_found"
}
defaultGeneral Error. The request may or may not be safe to retry, depending on the HTTP method, response status code, and whether a response was received. - If no response is returned from the API, a network error or timeout likely occurred. - In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results. The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**. The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout. Any request that returns a `503 Service Unavailable` response is always safe to retry. Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress. application/json
objectGeneralError
codestringrequired

default ""

messagestringrequired

Error message

request_idstring

Unique identifier for the request, useful for debugging. You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.

Example response
{
  "code": "",
  "message": "string",
  "request_id": "string"
}
Documentation menu