Logs

Branch logs let you inspect PostgreSQL server output across the primary and replicas of a branch. Logs are useful for debugging slow queries, connection issues, replication problems, and other runtime behavior. Branch logs are generally available on every branch — no opt-in or feature flag is required.

Viewing logs in the dashboard

Open a branch in the Xata dashboard and select Logs in the branch sidebar to browse entries in a searchable viewer. From the Logs page you can:

Pick a preset or custom time range.
Filter by level (error, warning, info, debug), instance (primary or a specific replica), and process.
Search log message bodies with substring or regex matching.
Click any entry to open a details panel with the full message and metadata.
Use Refresh to fetch the latest entries for the current time range.

For programmatic access — for example, shipping logs to an external observability tool — use the API described below.

Retrieving logs

Use the branchLogs endpoint to fetch logs for a time range. The endpoint requires the logs:read scope on your API key.

curl -X POST "https://api.xata.tech/organizations/{organizationId}/projects/{projectId}/branches/{branchId}/logs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-06-09T00:00:00Z",
    "end":   "2026-06-09T01:00:00Z",
    "limit": 100
  }'

The response contains a logs array of entries and a nextCursor that you can pass back in a follow-up request to page through additional results.

{
  "start": "2026-06-09T00:00:00Z",
  "end": "2026-06-09T01:00:00Z",
  "logs": [
    {
      "timestamp": "2026-06-09T00:00:01.234Z",
      "instanceID": "branch-xxx-1",
      "level": "info",
      "process": "postgres",
      "message": "database system is ready to accept connections"
    }
  ],
  "nextCursor": null
}

Request parameters

Field	Type	Description
`start`	`string` (RFC 3339)	Start of the time range. Required.
`end`	`string` (RFC 3339)	End of the time range. Required.
`limit`	`integer`	Maximum number of entries to return. Default `100`, maximum `200`.
`cursor`	`string`	Pagination cursor returned by a previous response.
`filters`	`array`	Optional filters. Multiple filters are combined with `AND`.

Log entry fields

Field	Description
`timestamp`	Time the log was emitted.
`instanceID`	Instance that produced the entry (primary or replica).
`level`	One of `debug`, `info`, `warning`, `error`.
`process`	Name of the PostgreSQL process that emitted the log.
`message`	The log message.

Filtering

Pass one or more filters to narrow results. Each filter applies to a specific field with an op and either a value or values:

Field	Description
`instance`	Filter by instance ID.
`level`	Filter by log level.
`process`	Filter by PostgreSQL process name.
`body`	Filter by the log message body.

Supported operators:

in — match any value in values (use with instance, level, process).
contains / icontains — substring match on the log body (case-sensitive / insensitive).
regex / iregex — regular-expression match on the log body.

For example, fetch only error-level entries from the primary instance that mention deadlock:

curl -X POST "https://api.xata.tech/organizations/{organizationId}/projects/{projectId}/branches/{branchId}/logs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-06-09T00:00:00Z",
    "end":   "2026-06-09T01:00:00Z",
    "filters": [
      { "field": "level",    "op": "in",        "values": ["error"] },
      { "field": "instance", "op": "in",        "values": ["branch-xxx-1"] },
      { "field": "body",     "op": "icontains", "value":  "deadlock" }
    ]
  }'

Credential redaction

Branch logs are scrubbed before they reach the API response. If a CREATE ROLE, ALTER ROLE, CREATE USER, ALTER USER, CREATE GROUP, ALTER GROUP, or CREATE/ALTER USER MAPPING statement appears in a log line, the statement is truncated at the PASSWORD keyword and the secret is replaced with <REDACTED>. This applies to both single-line and multi-line log records. For example, a log line like:

LOG: statement: ALTER ROLE app_user WITH PASSWORD 'hunter2'

is returned as:

LOG: statement: ALTER ROLE app_user WITH PASSWORD <REDACTED>

Redaction is applied on the read path, so it covers historical entries as well as newly emitted logs. Other password mentions outside role and user-mapping statements are left untouched.

Pagination

When a response includes a non-null nextCursor, pass it back as cursor in the next request to fetch the following page. The start, end, limit, and filters should remain the same across paged requests.

curl -X POST "https://api.xata.tech/organizations/{organizationId}/projects/{projectId}/branches/{branchId}/logs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start":  "2026-06-09T00:00:00Z",
    "end":    "2026-06-09T01:00:00Z",
    "cursor": "<nextCursor from previous response>"
  }'

Getting Started

Core Concepts

Platform

Tutorials

Migration Guides

Automations

Guides

Updates

Viewing logs in the dashboard

Retrieving logs

Request parameters

Log entry fields

Filtering

Credential redaction

​Viewing logs in the dashboard

​Retrieving logs

​Request parameters

​Log entry fields

​Filtering

​Credential redaction

​Pagination

Viewing logs in the dashboard

Retrieving logs

Request parameters

Log entry fields

Filtering

Credential redaction

Pagination