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.

​
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

JWT Bearer token for authentication. 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