---
title: "Execute a SQL query."
method: POST
path: "/api/v1/sql"
tags: ["Database"]
---

# Execute a SQL query.

`POST /api/v1/sql`

## Request

- Base URL: `https://api.scalix.world`
- URL: `https://api.scalix.world/api/v1/sql`
- Auth: HTTP bearer

Runs a parameterized SQL statement against the tenant's database and returns the result set.

## Request body

- SqlRequest: A parameterized SQL query to execute against the tenant's database.
  - `query` string, required: The SQL statement, with `$1`, `$2`, … placeholders for params.
  - `params` object, nullable: Positional bind parameters for the placeholders, in order.
  - `timeline_id` string, nullable: Branch timeline to run the query against, as returned by `scalix_db_branch_create` (optionally in its `db_<timeline>` connection-string form). Omit for the project's primary. A timeline that is not a branch of this project is rejected — it never falls back to the primary (F17).

## Response `200`

Query results

- SqlResponse: Result set returned by a SQL query. Matches the wire shape produced by `http.rs::SqlResponse` - `columns` entries are objects (name + Postgres type), not bare strings.
  - `columns` SqlColumnInfo[], required: Result-set columns, in result order.
    - `name` string, required: Column name.
    - `type_oid` integer, required: PostgreSQL type OID.
    - `type_name` string, required: PostgreSQL type name.
  - `rows` object, required: Rows; each row is an array of cell values aligned to `columns`.
  - `row_count` integer, required: Number of rows returned (or affected).
  - `command` string, required: The SQL command tag (e.g. `SELECT`, `INSERT`).
  - `duration_ms` number, double, required: Server-side execution time in milliseconds.
  - `cost` SqlQueryCost, required: Per-query resource cost breakdown.
    - `compute_ms` number, double, required: Compute time consumed, in milliseconds.
    - `pages_read` integer, required: Pages read to serve the query.
    - `bytes_transferred` integer, required: Bytes transferred to the client.
    - `estimated_usd` number, double, required: Estimated cost in USD.

## Other responses

- `400`: Invalid SQL
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error

---

[API](https://skmtc.dev/scalix/apis/scalix-cloud-api.md) · [All operations](https://skmtc.dev/scalix/apis/scalix-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalix/apis/scalix-cloud-api/revisions/2c04ca0a90bb?raw)