---
title: "Execute SQL query"
method: POST
path: "/v0/query"
tags: ["Query"]
---

# Execute SQL query

`POST /v0/query`

## Request

- Base URL: `https://api.formo.so`
- URL: `https://api.formo.so/v0/query`
- Auth: HTTP bearer

Execute a SQL query against the project's analytics data. Only SELECT and WITH statements are allowed. LIMIT is capped at 1,000,000. Forbidden keywords: INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, etc.

## Request body

- object
  - `query` string, required: SQL query to execute

## Response `200`

Offset-paginated query results. The server doesn't own pagination here; `LIMIT` and `OFFSET` come from your SQL string and are echoed back. `total` is the row count before `LIMIT` was applied; `has_more` is true when there are additional rows beyond the current window.

- object
  - `data` object[], required: Result rows.
  - `total` integer, required: Total rows before LIMIT was applied.
  - `limit` integer, required: Applied LIMIT (parsed from your SQL; defaults to the server cap if absent).
  - `offset` integer, required: Applied OFFSET (parsed from your SQL; 0 if absent).
  - `has_more` boolean, required: True when `offset + data.length < total`; i.e. there's another page to fetch by re-running with a higher OFFSET.

## Other responses

- `400`: The request was rejected. `code` is either `INVALID_VALIDATION_REQUEST` (Zod schema mismatch; `details` carries a `{ fieldPath: message }` map) or `BAD_REQUEST` (semantic validation failure outside Zod, e.g. mismatched IDs, business-rule violations). Branch on `code`, not status, to tell the two apart.
- `401`: Missing or invalid API key.
- `403`: The API key is valid but lacks the required scope for this endpoint.
- `429`: Per-workspace rate limit exceeded. Inspect the `RateLimit-*` response headers and back off.
- `500`: An unexpected error occurred on the server. The error has been logged; retry with exponential backoff.

---

[API](https://skmtc.dev/formo/apis/formo-public-api.md) · [All operations](https://skmtc.dev/formo/apis/formo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/formo/apis/formo-public-api/revisions/67ada57df63c?raw)