Skip to main content
POST
/
v0
/
query
Run SQL query
curl --request POST \
  --url https://api.formo.so/v0/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "SELECT * FROM events LIMIT 100"
}
'
{
  "isSuccess": true,
  "data": {
    "data": [
      {
        "event": "page",
        "address": "0x123...",
        "timestamp": "2025-01-20T10:00:00Z"
      }
    ],
    "meta": {
      "total": 120,
      "limit": 100,
      "offset": 0
    }
  }
}
Run a read-only SQL query to read your data. See examples on the Explorer page.
Query API architecture diagram showing your service sending SQL queries to the Query API and receiving data from the Data Warehouse

​
Authentication

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

​
Request

  • Method: POST
  • Path: /v0/query
  • Body:
{
  "query": "SELECT * FROM events LIMIT 100"
}
Limits:
  • Query must be a single SELECT/WITH statement (read-only).
  • No comments or multiple statements.
  • LIMIT is required and must be <= 1000.

​
Response

200 OK returns rows plus pagination metadata inferred from the query: 
{
  "data": [
    {
      "event": "page",
      "address": "0x123...",
      "timestamp": "2025-01-20T10:00:00Z"
    }
  ],
  "meta": {
    "total": 120,
    "limit": 100,
    "offset": 0
  }
}

​
Errors

  • 400: missing query, invalid SQL, LIMIT over 1000, or missing project id.
  • 401: missing/invalid authorization header or API key.
  • 403: API key lacks query:read permission.
  • 404: project or read token not found.
  • 500: 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 Keys.

Body

application/json
​
query
string
required

SQL query to execute. Must be read-only (SELECT/WITH), single statement, no comments. LIMIT is capped at 1,000,000.

Response

Successfully executed SQL query

​
isSuccess
boolean
​
data
object