Run a SOQL query
Execute a ServerOps Query Language (SOQL) query against your org's
log events. The query is a single string in the q body field.
The response shape depends on whether the query includes a group by
clause:
- Without
group by(events query) returns{events, next_cursor, has_more}. Page size is 100 events; cursor-paginated. - With
group by(aggregation query) returns{field, groups}with up to 100 group rows ordered by count descending.
org_id and project_id are always derived from the authenticated
caller and cannot appear in queries; attempting to reference them
returns soql_reserved_field.
Requires logs:read scope.
Authorization
bearerAuth logs:readAPI token from your dashboard.
Format: so_live_... (production) or so_test_... (test mode).
Tokens carry one or more scopes. Request only the scopes your integration needs:
| Scope | Grants |
|---|---|
media:read | List and retrieve files |
media:write | Upload and delete files |
logs:read | Read log entries |
logs:write | Ingest log entries |
cases:read | Read cases |
cases:write | Create and update cases |
apps:read | Read apps |
apps:write | Submit apps |
usage:read | Read quota usage |
members:read | List organisation members |
members:write | Invite and remove members |
billing:read | Read billing and subscription info |
tokens:write | Create and revoke API tokens |
In: header
Scope: logs:read
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/query" \ -H "Content-Type: application/json" \ -d '{ "q": "player_id:1337 AND event:weapon_pickup" }'{
"events": [
{
"event_id": "0192abcd-1234-7567-89ab-cdef01234567",
"ts": "2026-05-17T10:00:00.123Z",
"ingested_at": "2026-05-17T10:00:00.456Z",
"org_id": "org_abc123",
"project_id": "proj_def456",
"dataset": "security",
"severity": "warn",
"event": "auth_fail",
"actor": "user:42",
"source": "fivem",
"message": "bad creds",
"payload": {
"ip": "1.2.3.4"
},
"bytes_raw": 128
}
],
"next_cursor": "",
"has_more": false
}{
"error": {
"code": "soql_parse_error",
"message": "string",
"position": 0,
"near": "string",
"field": "string"
}
}{
"error": {
"code": "unauthorized",
"message": "missing or invalid authorization token"
}
}{
"error": {
"code": "not_found",
"message": "file not found"
}
}{
"error": {
"code": "forbidden",
"message": "token does not have the required scope"
}
}{
"error": {
"code": "quota_exceeded",
"message": "tier quota exceeded for storage_bytes",
"metric": "storage_bytes",
"quotas": [
{
"metric": "storage_bytes",
"used": 10737418240,
"limit": 10737418240,
"cumulative": true
}
]
}
}{
"error": {
"code": "internal",
"message": "an unexpected error occurred"
}
}{
"error": {
"code": "not_found",
"message": "file not found"
}
}