# List branch log field values

`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](/guides/apis-sdks-reference-api-logs-list-project-branch-log-field-values)

```bash title="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

::::tabs
:::tab{title="CLI"}
```bash
neon logs field-values <branch_id>
```
:::

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

:::tab{title="MCP"}
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.

## Related pages

- [List branch log fields](./apis-sdks-reference-api-logs-list-project-branch-log-fields.md)
- [Query branch logs](./apis-sdks-reference-api-logs-query-project-branch-logs.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.