Neon API (unofficial showcase)
GET/projects/{project_id}/branches/{branch_id}/logs/fields/{field_name}/values

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

8 parameters
project_idstringrequired
The Neon project ID
branch_idstringrequired
The Neon branch ID
field_namestringrequired
The log field whose distinct values should be returned. Must be one of the names returned by the log fields endpoint for this branch.
sincestringoptional
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_timestringoptional
Inclusive beginning of the lookup window. Mutually exclusive with `since`.
end_timestringoptional
Exclusive end of the lookup window. Defaults to the current time.
sourcestringoptional
Only consider records emitted by this Neon service.
Allowed:functionstoragepg_endpoint
limitintegeroptional
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

4 status codes
200Distinct values for the requested log field
valuesarray<string>required
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`.
400The lookup could not be served as written. The body is always `ProjectBranchLogsInvalidQuery` — see `reason` for the exact cause.
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.
Allowed:time_range_too_largeinvalid_time_rangeconflicting_time_rangeinvalid_cursorunknown_fieldinvalid_logqlconflicting_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.
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.
Allowed:branch_not_foundtelemetry_not_enabled
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.
request_idstringoptional
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.
codestringrequired
Machine-readable code classifying the error type. See `message` for a human-readable explanation.
Default:
messagestringrequired
Error message

Error handling

A 400 is returned: The lookup could not be served as written. The body is always ProjectBranchLogsInvalidQuery — see reason for the exact cause. A 404 is returned: 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. Any other status is an error: General 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.