List branch log field values

Lists the distinct values observed for a low-cardinality log field in

GET /projects/{project_id}/branches/{branch_id}/logs/fields/{field_name}/valuesbeta

Lists the distinct values observed for a low-cardinality log field in the requested time range. Call the log fields endpoint first to learn which field_name values this branch supports; a field that branch has never emitted is rejected with unknown_field.

Give the window either as since or as an explicit start_time; supplying both is rejected. If neither is given, the previous six hours are used. The maximum supported time range is seven days.

Note: This endpoint is currently in Private Beta.

Markdown for AI context

REST API - curl

curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/logs/fields/$FIELD_NAME/values" \
  -H "Authorization: Bearer $NEON_API_KEY"

Every field below is optional. An empty body works too.

Also available in

Bash

neon logs field-values <branch_id>

Tool: list_log_field_values

List the distinct values of a log field (e.g. all service_name or severity_text values seen) within a branch and time window. Use values with the corresponding query_logs structured input when one exists, or with raw logql otherwise. The field must be one of the names list_log_fields reports for the branch; anything else is rejected as an unknown field rather than returning an empty list. truncated: true means more distinct values exist than were returned because the endpoint's result limit or server scan cap was reached, so the list is an arbitrary subset — narrow the time window and ask again before filtering on it.

projectId (string, optional) The ID of the project. Defaults to your only project if unambiguous.
branchId (string, optional) The ID of the branch. Defaults to the project's default branch.
field (string, required) The log field (label) whose distinct values to list, e.g. "service_name" or "severity_text". Use list_log_fields to discover valid field names.
since (string, optional) Relative lookback window as a duration (e.g. "6h", "24h"). If omitted, the server default lookback (6 hours) applies; the maximum supported window is 7d.

Parameters

Project ID

project_id

string

The Neon project ID

Branch ID

branch_id

string

The Neon branch ID

Field name

field_name

string

The log field whose distinct values should be returned. Must be one of the names returned by the log fields endpoint for this branch.

Since

since

string

Length of the lookup window, ending at end_time or at the current time when end_time is omitted. Mutually exclusive with start_time. Defaults to six hours.

Start time

start_time

string

Inclusive beginning of the lookup window. Mutually exclusive with since.

End time

end_time

string

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

Source

source

string

Only consider records emitted by this Neon service.

Limit

limit

integerdefault: 100

Maximum number of distinct values to return. The response sets is_truncated when this bound, or the server's own scan cap, cut the list short.

Response

200

Distinct values for the requested log field

Depth

"values": (array),req

"is_truncated": (boolean),req

Errors

400

The lookup 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.