Skip to main content
POST
Run a read-only SQL query to read your data. See examples on the Explorer page.

​
Authentication

Use a Workspace API Key with query:read permission. Send it in the Authorization header:

​
Request

  • Method: POST
  • Path: /v0/query
  • Body:
Limits:
  • Query must be a single SELECT/WITH statement (read-only).
  • No comments or multiple statements.
  • LIMIT is optional (defaults to 100 rows if omitted) and must be <= 1000000.

​
Response

200 OK returns rows plus pagination metadata reflecting the LIMIT / OFFSET you wrote into the SQL.
This endpoint uses limit/offset (not page/size) because the client controls pagination directly through the SQL query - Formo just echoes the values back.

​
Errors

Branch on error.code; see Errors for the full reference.
  • 400 BAD_REQUEST: missing query, invalid SQL, LIMIT over 1,000,000, or missing project id.
  • 401 UNAUTHORIZED: missing/invalid authorization header or API key.
  • 403 FORBIDDEN: API key lacks query:read scope.
  • 404 NOT_FOUND: project or read token not found.
  • 429 TOO_MANY_REQUESTS: per-workspace rate limit exceeded.
  • 500 INTERNAL_SERVER_ERROR: failure executing the query.

Authorizations

​
Authorization
string
header
required

Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API.

Body

application/json
​
query
string
required

SQL query to execute

Response

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.

​
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.