Skip to main content
Neon Postgres Docs

Search documentation

Type to search this documentation.

List branch log field values

GET/projects/{project_id}/branches/{branch_id}/logs/fields/{field_name}/valuesList branch log field values

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.

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}$

field_namestringpathrequired

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

minLength 1

sincestringquery

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.

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

start_timestring · date-timequery

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

end_timestring · date-timequery

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

sourcestringquery

Only consider records emitted by this Neon service.

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

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

limitintegerquery

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.

default 100 · maximum 1000 · minimum 1

Responses

200Distinct values for the requested log fieldapplication/json
objectProjectBranchLogFieldValuesResponse
is_truncatedbooleanrequired

True when more distinct values exist than were returned, because either the requested `limit` or the server's own scan cap was reached. A caller that filters on a partial list is choosing from an arbitrary subset, so narrow `since` or `source` and ask again when this is `true`.

valuesarray of stringrequired
Show child attributes
Example response
{
  "is_truncated": true,
  "values": [
    "string"
  ]
}
400The lookup 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