---
title: "Query a site's database"
method: POST
path: "/sites/{id}/db/query"
tags: ["Sites"]
---

# Query a site's database

`POST /sites/{id}/db/query`

## Request

- Base URL: `https://api.crevio.co/v1`
- URL: `https://api.crevio.co/v1/sites/{id}/db/query`
- Auth: API key in header `Authorization`

Run SQL against a site's database.

**Against production this reads only** — `SELECT`, `WITH`, `PRAGMA`, `EXPLAIN`. A write here would leave no record of what ran, no restore point and nobody asked, so data changes go through `db/migrate` and shape changes go through the development database and a deploy.

The development database accepts anything: it holds no customer data, and experimenting on it is what it is for.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `sql` string, required: The SQL to execute. Multiple statements may be separated by `;` — the last statement that returns rows is surfaced.
  - `environment` 'development' | 'production': Which database to use. A site normally has exactly one, `production`, and that is the default — the live database the site reads. `development` is only valid if a separate development database has been provisioned for this site; asking for one that doesn't exist is an error rather than a silent fall back to production. The response echoes the environment that was used.

## Response `200`

Query result

- DatabaseQueryResult
  - `object` string, required: Always "database_query_result".
  - `rows` object[], required: The rows returned by the query, each an object keyed by column name.
  - `row_count` integer, required: Number of rows returned.
  - `meta` object, nullable: Execution metadata for the surfaced statement (e.g. rows read/written, duration).

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `404`: Resource not found
- `422`: Validation error
- `429`: Rate limit exceeded — 600 requests per minute per credential. Retry after the number of seconds in `Retry-After`.

---

[API](https://skmtc.dev/crevio/apis/crevio-api-v1.md) · [All operations](https://skmtc.dev/crevio/apis/crevio-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/crevio/apis/crevio-api-v1/revisions/2219f18ad651?raw)