Execute SQL query

curl --request POST \ --url https://{branch}.{region}.xata.tech/sql \ --header 'Connection-String: <api-key>' \ --header 'Content-Type: application/json' \ --data ' { "query": "SELECT id, name FROM users WHERE id = $1", "params": [ 42 ] } '

{ "fields": [ { "name": "id", "tableID": 0, "columnID": 0, "dataTypeID": 23, "dataTypeSize": 4, "dataTypeModifier": -1, "format": "text" }, { "name": "name", "tableID": 0, "columnID": 0, "dataTypeID": 25, "dataTypeSize": -1, "dataTypeModifier": -1, "format": "text" } ], "command": "SELECT", "rowCount": 1, "rows": [ { "id": 42, "name": "Ada" } ], "rowAsArray": false }

Authorizations

Connection-String

string

header

required

Branch PostgreSQL connection string (postgres://user:pass@{branch}.{region}.xata.tech/db), including the embedded password. The hostname selects the target branch, region, and endpoint type (the -rw/-ro suffix, see EndpointType), and must match the request host. Obtain it from the Xata dashboard or the control-plane API. This is the only credential the gateway accepts; the control-plane API key (Bearer token) is rejected here. For the WebSocket endpoint (GET /v2) the same connection string is conveyed via the PostgreSQL startup message instead of this header.

Headers

Array-Mode

enum<string>

When true, return rows as arrays instead of objects.

Available options:

true,

false

Raw-Text-Output

enum<string>

When true, return all values as strings without type conversion.

Available options:

true,

false

Batch-Isolation-Level

enum<string>

Transaction isolation level for batch queries.

Available options:

ReadCommitted,

ReadUncommitted,

RepeatableRead,

Serializable

Batch-Read-Only

enum<string>

When true, execute the batch transaction in read-only mode.

Available options:

true,

false

Batch-Deferrable

enum<string>

When true, execute the batch transaction in deferrable mode.

Available options:

true,

false

Body

application/json

SQL query request. Provide either query for a single query or queries for a batch.

query

string

SQL query to execute (single query mode).

params

any[]

Positional parameters for the query ($1, $2, ...).

queries

object[]

Array of queries for batch execution within a single transaction.

Show child attributes

arrayMode

boolean

Override array mode for this query (single query mode only).

Response

Query executed successfully

Option 1
Option 2

Result of a single SQL query execution.

fields

object[]

required

Column metadata for the result set.

Show child attributes

command

string

required

PostgreSQL command tag (e.g. SELECT, INSERT, UPDATE, DELETE).

rowCount

integer | null

required

Number of rows affected by the command.

rows

any[]

required

Result rows. Each row is an object (column-name keys) or an array (when array mode is enabled).

rowAsArray

boolean

required

Whether rows are returned as arrays (true) or objects (false).