---
title: "Execute SQL query - Xata"
description: "Execute a single SQL query or a batch of queries against a PostgreSQL branch. Authentication: send the branch's PostgreSQL connection string in the Connection-String header. The control-plane API key (Bearer token) is not accepted on the gateway host. Routing: the target branch, region, and endpoint type are taken from the hostname embedded in the connection string, which must match the request host. See the Connection-String security scheme for the host format. Single query: provide query (and optional params) at the top level. Batch: provide queries as an array of query objects, or send the request body as a JSON array. Batch queries execute within a single transaction."
source: "https://xata.io/docs/api-reference/gateway/execute-sql-query"
---

Skip to main content

POST

/

sql

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`).

Was this page helpful?

[Previous](/docs/api-reference/api-keys/bulk-delete-api-keys-for-the-authenticated-user)

[WebSocket wire protocol proxy](/docs/api-reference/gateway/websocket-wire-protocol-proxy)

[Next](/docs/api-reference/gateway/websocket-wire-protocol-proxy)