For AI agents: markdown of this page — /docs-content-en/infra/database/query.md documentation index — /llms.txt

Run a read-only SQL query

POST /v1/infra/servers/:id/db/query

Runs one read-only SQL query against the application's SQLite database and returns the result columns and rows. Use it for queries with conditions, joins and aggregates that reading the rows of a single table does not support.

Database access conditions and request limits — When the database is available and Limits. To change data — Run write SQL.

Parameters

Parameter	Type	Required	Description
Parameter`id` (path)	Typestring (UUID)	Requiredyes	DescriptionID of an application with `kind` equal to `GALAXY_APP`. List: `GET /v1/infra/servers`

Request fields (body)

Field	Type	Required	Description
Field`sql`	Typestring	Requiredyes	DescriptionOne read-only SQL statement, up to 16,384 bytes in UTF-8. Values are bound through positional `?` placeholders
Field`parameters`	Typearray	Requiredno	DescriptionValues for the `?` placeholders in order, up to 256 items. Each is a string up to 16,384 characters, a finite number or `null`. Booleans are not accepted; pass `1` and `0` instead. Default: `[]`
Field`file`	Typestring	Requiredno	DescriptionDatabase file path relative to `/data`, up to 1024 bytes in UTF-8. File list — `data.files[].file` in `GET /db`. Default — `data.defaultFile` from the same response

Other body fields return 400 VALIDATION_ERROR. The body is limited to 64 KiB.

Pagination. The endpoint has no cursor or page number: with data.truncated: true, rows beyond the limit are dropped. Fetch the rest with the next query: add a stable ORDER BY sort and LIMIT with OFFSET to sql, or a condition on the key of the last row received, for example WHERE id > ?.

Examples

curl — personal key

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/APP_ID/db/query" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT id, name, email FROM customers WHERE id > ? ORDER BY id",
    "parameters": [1]
  }'

curl — OAuth application

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/APP_ID/db/query" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT id, name, email FROM customers WHERE id > ? ORDER BY id",
    "parameters": [1]
  }'

JavaScript — personal key

javascript

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${appId}/db/query`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sql: 'SELECT id, name, email FROM customers WHERE id > ? ORDER BY id',
      parameters: [1],
    }),
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.details?.reason ?? error.message}`)
// Rows are positional arrays in data.columns order
const rows = data.rows.map(r => Object.fromEntries(data.columns.map((c, i) => [c, r[i]])))
console.log(rows, data.truncated ? 'result truncated' : '')

JavaScript — OAuth application

javascript

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${appId}/db/query`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sql: 'SELECT id, name, email FROM customers WHERE id > ? ORDER BY id',
      parameters: [1],
    }),
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
console.log(data.columns, data.rows)

Response fields

Field	Type	Description
Field`success`	Typeboolean	Description`true` on success
Field`data.file`	Typestring	DescriptionPath of the file read, relative to `/data`
Field`data.columns`	Typearray	DescriptionResult column names in order. Duplicate names, for example after a join, remain separate items
Field`data.rows`	Typearray	DescriptionResult rows, up to 500. Each row is an array of values in `data.columns` order
Field`data.rows[][]`	Typestring \| number \| null \| object	DescriptionCell value. Text as a string, numbers as a number, SQL `NULL` as `null`. Values that cannot be passed as a JSON number or string come as an object with a `type` field — see the three rows below
Field`data.rows[][]` with `type: "blob"`	Typeobject	DescriptionBinary data; the `base64` field holds the Base64-encoded content
Field`data.rows[][]` with `type: "integer"`	Typeobject	DescriptionAn integer with absolute value greater than 9,007,199,254,740,991; the `value` field holds the number as a string
Field`data.rows[][]` with `type: "float"`	Typeobject	DescriptionInfinity or not-a-number; the `value` field is `Infinity`, `-Infinity` or `NaN`
Field`data.rowCount`	Typeinteger	DescriptionNumber of rows in `data.rows`
Field`data.truncated`	Typeboolean	Description`true` if the result was truncated: more than 500 rows or the response approached 1 MiB. Rows beyond the limit are not returned
Field`data.durationMs`	Typenumber	DescriptionRead time on the host in milliseconds

Response example

JSON

{
  "success": true,
  "data": {
    "file": "app.db",
    "columns": ["id", "name", "email"],
    "rows": [
      [2, "Customer B", "b@example.com"],
      [3, "Customer C", null]
    ],
    "rowCount": 2,
    "truncated": false,
    "durationMs": 0.75
  }
}

Error response example

422 — the query tries to change data: