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"
}
'
{
  "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

Bearer token for authentication. Use an SDK Write Key for the Events API, or a Workspace API Key for the Query and Profiles APIs. Format: 'Bearer '

Body

application/json
​
query
string
required

SQL query to execute. Must be read-only (SELECT/WITH), single statement, no comments, and include LIMIT <= 1000.

Response

Successfully executed SQL query

​
data
object[]
required

Rows returned by the SQL query

​
meta
object
required