# Query branch logs

`POST /projects/{project_id}/branches/{branch_id}/logs/querybeta`

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.

[Markdown for AI context](/guides/apis-sdks-reference-api-logs-query-project-branch-logs)

```bash title="REST API - curl"
curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/logs/query" \
  -X POST \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Also available in

::::tabs
:::tab{title="CLI"}
```bash
neon logs query
```
:::

:::tab{title="SDK"}
:::

:::tab{title="MCP"}
Tool: `query_logs`

Query logs emitted by your Neon serverless functions (and other services like storage). Logs are OpenTelemetry-based; this tool exposes them through structured filters so you don't have to write a query language. Use this tool when the user wants to: - See recent logs / errors for a function or service - Investigate a failure ("why did my function error in the last hour?") - Correlate logs to a distributed trace via trace\_id

1. For structured queries, pick the source (defaults to "function") and optionally narrow by serviceName, minSeverity, or bodyContains. For a raw query, supply `logql` and omit structured filters. 2. Set a time window: `since` (relative, e.g. "1h" — default, optionally ending at endTime) OR startTime/endTime (absolute RFC3339). 3. Use list\_log\_fields / list\_log\_field\_values first if you need to discover valid service names or severities.

- - Defaults to the project's default branch and the last 1 hour if unspecified. - Results are newest-first and capped by `limit` (default 100); `truncated: true` means more records matched than were returned — narrow the filters or time range. - `minSeverity` follows OTel ordering (trace < debug < info < warn < error < fatal), so "error" also returns FATAL. - The returned preferred `logql` field and legacy `query` field contain the LogQL these filters stand for. Always pass `logql` back to refine it by hand. - Advanced: pass raw `logql` instead of the structured filters. Only stream selectors `{label="v"}` and line filters (|= |\~ != !\~) are supported — no aggregations or parsers. Combining `logql` with structured filters is rejected. - `query` remains available as a legacy input alias for `logql` and preserves its previous override behavior: when supplied, structured filters are ignored. Do not supply both raw fields.

- `projectId` (string, optional)
  The ID of the project whose logs to query. If omitted and you have exactly one project, that project is used.

- `branchId` (string, optional)
  The ID of the branch whose logs to query. Defaults to the project's default branch.

- `source` (enum, optional)
  Which service produced the logs. "function" (serverless functions) is the default; "storage" and "pg\_endpoint" are also available.

- `serviceName` (string, optional)
  Filter to a specific OTel service name (service.name).

- `minSeverity` (enum, optional)
  Return only logs at this OTel severity level or above (trace < debug < info < warn < error < fatal). E.g. "error" returns ERROR and FATAL.

- `severityText` (string, optional)
  Filter to an exact severity text (e.g. "ERROR"). Takes precedence over minSeverity.

- `bodyContains` (string, optional)
  Return only logs whose rendered message contains this case-sensitive substring. Structured messages use compact JSON, so match JSON syntax such as `"http_status":200`, not prose such as `http_status: 200`.

- `traceId` (string, optional)
  Correlate to a distributed trace: return only logs with this trace\_id.

- `since` (string, optional)
  Relative lookback window ending at `endTime`, or now when omitted, as a duration (e.g. "30m", "1h", "24h"). Defaults to the last hour; the maximum supported window is `7d`. Ignored when startTime is set.

- `startTime` (string, optional)
  Absolute start of the window, RFC3339 (e.g. "2026-07-16T09:00:00Z"). Overrides `since`; the startTime/endTime window must not span more than seven days.

- `endTime` (string, optional)
  Absolute end of the window, RFC3339. Ends either a relative `since` window or an absolute `startTime` window; defaults to now.

- `limit` (number, optional, default: 100)
  Maximum number of log lines to return (1-1000, default 100). Large results are truncated server-side.

- `logql` (string, optional)
  Advanced: a raw LogQL expression to run instead of the structured filters above (e.g. `{entity_type="function"} |~ "(?i)timeout"`). Only stream selectors and line filters are supported — no aggregations or parser stages. Do not combine it with structured filters.

- `query` (string, optional)
  Legacy compatibility alias for `logql`. Preserves the previous behavior of overriding any structured filters. Do not supply both raw fields.
:::
::::

## Parameters

Project ID

`project_id`

string

The Neon project ID

Branch ID

`branch_id`

string

The Neon branch ID

## Request body

No field is required.

Since

`since`

string

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

Limit

`limit`

integerdefault: 100

Maximum number of log records to return per page.

min: 1, max: 1000

Cursor

`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

`sort_order`

stringdefault: desc

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

ascdesc

Source

`source`

string

The Neon service that emitted the log record.

functionstoragepg\_endpoint

Service name

`service_name`

string

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

≥1 chars

Scope name

`scope_name`

string

Match the OpenTelemetry instrumentation scope name exactly.

≥1 chars

Minimum severity

`minimum_severity`

string

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

tracedebuginfowarnerrorfatal

Severity text

`severity_text`

string

Match the OpenTelemetry severity text exactly.

≥1 chars

Body contains

`body_contains`

string

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.

≥1 chars

Trace ID

`trace_id`

string

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

`logql`

string

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.

≥1 chars

Start time

`start_time`

string

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

`end_time`

string

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

## Response

200

Logs matching the supplied filters

Depth

"is\_truncated": (boolean),req

"next\_cursor": (string),

## Errors

400

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

404

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

default

General error

This endpoint can return the standard Neon API error response.

Response fields

- `message` Required. Human-readable error message.
- `code` Required. Machine-readable error code.
- `request_id` Optional. Request identifier for debugging. You can provide one with the `X-Request-ID` header.

Retry guidance

If no response is returned, the request may still have reached the server. This is why retry safety depends on the method and status code.

Idempotent methods (`GET`, `HEAD`, `OPTIONS`) are generally safe to retry after a network error or timeout. Non-idempotent methods (`POST`, `PATCH`, `DELETE`, `PUT`) can change state, so avoid automatic retries unless your workflow can tolerate duplicate effects.

Responses with `423 Locked` or `503 Service Unavailable` are safe to retry. `423 Locked` means the resource is temporarily locked, usually because another operation is in progress.

## Related pages

- [List branch log field values](./apis-sdks-reference-api-logs-list-project-branch-log-field-values.md)
- [List branch log fields](./apis-sdks-reference-api-logs-list-project-branch-log-fields.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.