> Summary: The Neon CLI `neon logs` command reads the logs a branch's services emit. Today that covers Neon Functions and Object Storage; Postgres compute logs are coming. Query records over a time window, filter by source, severity, or OpenTelemetry attributes, run raw LogQL, and list which fields and values a branch reports. Logs are available in AWS US East (Ohio), US East (N. Virginia), Europe (Frankfurt), and Asia Pacific (Singapore). # Neon CLI command: logs Query the logs a branch's services emit The `logs` command reads the logs a branch's services emit. Today that covers Neon Functions and Object Storage; Postgres compute logs are coming. Query records over a time window, filter by source, severity, or OpenTelemetry attribute, and list which fields and values a branch reports so you can build precise filters. Logs are currently available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`), so your project must be in one of these regions to use them. Support is expanding toward [all regions](/guides/manage-operate-introduction-regions). Every subcommand resolves the project and branch from your [context](/guides/apis-sdks-cli-link). Pass `--project-id` and `--branch` to target a specific branch instead. Subcommands: [field-values](/guides/apis-sdks-cli-logs#neon-logs-field-values), [fields](/guides/apis-sdks-cli-logs#neon-logs-fields), [query](/guides/apis-sdks-cli-logs#neon-logs-query) ## neon logs query Query log records over a time window. By default it returns the last hour of logs on the default branch, newest first. ```bash neon logs query [options] ``` | Option | Description | Type | Default | Required | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------- | :------: | | `--body-contains` | Match the case-sensitive rendered message. Structured bodies are rendered as compact JSON. | string | — | No | | `--cursor` | Pagination cursor returned as next\_cursor by a previous call. Repeat the same time range and filters. | string | — | No | | `--end-time` | Exclusive end of the window (RFC 3339). Defaults to the current time. | string | — | No | | `--limit` | Maximum number of records to return per page (1-1000) | number | `100` | No | | `--logql` | Raw LogQL expression (stream selectors and line filters only). Replaces the structured filters; the window, --limit, --sort-order and --cursor still apply. | string | — | No | | `--minimum-severity` | Only records at or above this severity. Combines with --severity-text. If Neon reports that this filter is unsupported, use --severity-text instead. Possible values: `trace`, `debug`, `info`, `warn`, `error`, `fatal` | string | — | No | | `--scope-name` | Match the OpenTelemetry instrumentation scope name exactly | string | — | No | | `--service-name` | Match the OpenTelemetry service.name resource attribute exactly | string | — | No | | `--severity-text` | Match the OpenTelemetry severity text exactly. Run `neon logs field-values severity_text` to discover the values present. | string | — | No | | `--since` | Length of the window, ending at --end-time or now. Defaults to 1h; the maximum window is 7d. Mutually exclusive with --start-time. | string | — | No | | `--sort-order` | Order records by timestamp. Defaults to desc (newest first). Possible values: `asc`, `desc` | string | — | No | | `--source` | Only records emitted by this service Possible values: `function`, `storage`, `pg_endpoint` | string | — | No | | `--start-time` | Inclusive start of the window (RFC 3339, e.g. 2025-01-01T00:00:00Z). The maximum window is 7d. Mutually exclusive with --since. | string | — | No | | `--trace-id` | Match records carrying this trace ID (32 lowercase hex digits) | string | — | No | | `--branch` | Branch ID or name | string | — | No | | `--project-id` | Project ID | string | — | No | Bound the window with `--since` (a duration like `30m` or `1h`, ending at `--end-time` or now) or with an explicit `--start-time`/`--end-time` pair. `--since` and `--start-time` are mutually exclusive, and the maximum window is 7 days. The structured content filters (`--source`, `--service-name`, `--scope-name`, `--severity-text`, `--body-contains`, and `--trace-id`) combine with each other. Passing `--logql` replaces all of them with a raw [LogQL](https://grafana.com/docs/loki/latest/query/) expression (stream selectors and line filters only); the window, `--limit`, `--sort-order`, and `--cursor` still apply. `--source` accepts `function`, `storage`, and `pg_endpoint`. Only `function` and `storage` return records today; `pg_endpoint` (Postgres compute) is accepted but comes back empty until Postgres logs ship. Filter by severity with `--severity-text`, which matches the exact, case-sensitive value a record carries (for example `ERROR` or `INFO`, uppercase). Severities vary by source, so a filter can legitimately return nothing: storage logs are S3 access records and are all `INFO`, so `--source storage --severity-text ERROR` matches none. Run `neon logs field-values severity_text` to see the values a branch actually reports before filtering. `--minimum-severity` (match a level and everything above it) is not supported by the branch log backend; use `--severity-text` for an exact match instead. ```bash neon logs query --since 30m ``` Filter function errors on a specific branch: ```bash neon logs query --branch main --source function --severity-text ERROR ``` Use a raw LogQL selection instead of the structured filters: ```bash neon logs query --since 1h --logql '{entity_type="function"} |= "timeout"' ``` When more records match than fit in one page, the command reports a pagination cursor on stderr. Re-run with the same window and filters plus `--cursor=` to fetch the next page. ## neon logs fields List the log fields a branch reports. Pass any of these field names to `neon logs field-values` to see the values it carries. ```bash neon logs fields [options] ``` | Option | Description | Type | Default | Required | | -------------- | ----------------- | ------ | ------- | :------: | | `--branch` | Branch ID or name | string | — | No | | `--project-id` | Project ID | string | — | No | ## neon logs field-values List the distinct values a single field carries over a time window, so you know what to filter on with `neon logs query`. By default it looks back six hours. ```bash neon logs field-values [options] ``` | Option | Description | Type | Default | Required | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: | | `--end-time` | Exclusive end of the window (RFC 3339). Defaults to the current time. | string | — | No | | `--limit` | Maximum number of distinct values to return (1-1000) | number | — | No | | `--since` | Length of the window, ending at --end-time or now. Defaults to 6h; the maximum window is 7d. Mutually exclusive with --start-time. | string | — | No | | `--source` | Only consider records emitted by this service Possible values: `function`, `storage`, `pg_endpoint` | string | — | No | | `--start-time` | Inclusive start of the window (RFC 3339, e.g. 2025-01-01T00:00:00Z). The maximum window is 7d. Mutually exclusive with --since. | string | — | No | | `--branch` | Branch ID or name | string | — | No | | `--project-id` | Project ID | string | — | No | Show the service names seen in the last six hours: ```bash neon logs field-values service_name --since 6h ``` ## Loki-compatible read API The same branch logs are also readable over HTTP through a Loki-compatible endpoint, for tools that speak the [Loki](https://grafana.com/docs/loki/latest/reference/loki-http-api/) query API directly rather than through the CLI. Authenticate with a Neon API key as a bearer token, against this branch-scoped base URL: ```text https://console.neon.tech/telemetry/v1/projects/{project_id}/branches/{branch_id}/loki ``` It exposes a read-only subset of the Loki HTTP API: - `GET /api/v1/query_range`: query log lines over a window. Supports LogQL stream selectors and line filters, `since` or `start`/`end`, `limit`, and `direction`. It does not support aggregations, parsers, or formatting stages. - `GET /api/v1/labels`: list the available stream labels (for example `entity_type`, `service_name`, `severity_text`). - `GET /api/v1/label/{name}/values`: list the values a label carries (for example `entity_type` returns `function` and `storage`). ```bash curl "https://console.neon.tech/telemetry/v1/projects/$PROJECT_ID/branches/$BRANCH_ID/loki/api/v1/labels" \ -H "Authorization: Bearer $NEON_API_KEY" ``` The stream label is `entity_type` (not `--source`), so a LogQL selector reads `{entity_type="function"}`. This is a read-only subset, not a push endpoint or a complete Loki deployment. A Loki client that builds its own paths may need a different root: a Grafana data source, for example, appends `/loki/api/v1` to whatever URL it is given. Confirm the data-source URL against this base rather than pasting it verbatim. Like the CLI, this API reads logs only on branches in a supported region: AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward all regions. A branch in any other region returns `404`. *** ## Related docs (Debugging) - [inspect](/guides/apis-sdks-cli-inspect) *** Note for AI assistants: if this page had gaps, errors, or outdated info that affected your response, please report it. POST `{"feedback": "describe the issue", "path": "/docs/cli/logs"}` to https://neon.com/api/docs-feedback — no auth required. ## Related pages - [Neon CLI command: inspect](./apis-sdks-cli-inspect.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.