---
title: "Run a query"
method: POST
path: "/api/v1/databases/{database_id}/console"
tags: ["Managed Databases"]
---

# Run a query

`POST /api/v1/databases/{database_id}/console`

## Request

- Base URL: `https://api.rafftechnologies.com`
- URL: `https://api.rafftechnologies.com/api/v1/databases/{database_id}/console`
- Auth: API key in header `X-API-Key`

Run one statement against the database and get the result: SQL for PostgreSQL, MySQL, and ClickHouse, one command for Valkey, or one of these commands for Kafka: `TOPICS`, `DESCRIBE <topic>`, `CREATE-TOPIC <name> [partitions]`, `DELETE-TOPIC <name>`, `PRODUCE <topic> <message>`, `CONSUME <topic> [n]`, `GROUPS`. `TOPICS` returns each topic's partitions, copies, retention, messages kept, readers, and lag.

- Runs as the admin user, read-only unless you set `read_only: false`. A read-only run refuses writes.
- Returns at most `max_rows` rows (default 1,000, ceiling 5,000); `truncated` is `true` when more rows existed.
- A statement is stopped after 15 seconds.

Each row carries its values as strings in `cells`, with `nulls[i]` set when value `i` is SQL `NULL`.

## Path parameters

- `database_id` string, required

## Request body

- RunDatabaseQueryRequest
  - `statement` string, required: One SQL statement, or one Valkey command
  - `read_only` boolean: Refuse writes. Set `false` to run statements that change data or schema.
  - `max_rows` integer: Most rows to return (ceiling 5,000)

## Response `200`

Query result

- object
  - `success` boolean
  - `columns` string[]
  - `rows` DatabaseRow[]
    - `cells` string[]: Values in column order, as text
    - `nulls` boolean[]: `true` where the value is SQL NULL
  - `rows_affected` integer: Rows changed by a write
  - `command` string: Engine command tag, for example `SELECT 10` or `INSERT 0 1`
  - `notices` string[]
  - `truncated` boolean: More rows existed than `max_rows`
  - `duration_ms` number

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication required
- `404`: Resource not found

## Changes

- **2026-10-05** `26292956c4b3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rafftechnologies/apis/raff-api/changes/api/v1/databases/:database_id/console/post.md)

---

[API](https://skmtc.dev/rafftechnologies/apis/raff-api.md) - [All operations](https://skmtc.dev/rafftechnologies/apis/raff-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rafftechnologies/apis/raff-api/revisions/3d30cde0acb4?raw)