Skip to main content
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.

​
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

FieldTypeDescription
startstring (RFC 3339)Start of the time range. Required.
endstring (RFC 3339)End of the time range. Required.
limitintegerMaximum number of entries to return. Default 100, maximum 200.
cursorstringPagination cursor returned by a previous response.
filtersarrayOptional filters. Multiple filters are combined with AND.

​
Log entry fields

FieldDescription
timestampTime the log was emitted.
instanceIDInstance that produced the entry (primary or replica).
levelOne of debug, info, warning, error.
processName of the PostgreSQL process that emitted the log.
messageThe 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:
FieldDescription
instanceFilter by instance ID.
levelFilter by log level.
processFilter by PostgreSQL process name.
bodyFilter 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" }
    ]
  }'

​
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>"
  }'