Live-tail a SOQL query (SSE)

Open a Server-Sent Events stream of new events matching the given SOQL filter. Each data: line is one event.

Availability

Live tail is a Logs Pro plan or higher feature. Hobby-tier orgs receive 402 Payment Required with the tier_upgrade_required code; upgrade at /dashboard/billing/plan.

Each token may hold at most 3 concurrent tail sessions per API host. Opening a 4th returns 429 Too Many Requests with the tail_session_limit_exceeded code; close an existing session and try again.

Wire protocol

• Content-Type: text/event-stream
• :heartbeat comment line every 15 seconds (so proxies and load balancers don't close the connection)
• Server closes the connection after 5 minutes of no matching events
• Up to 200 events delivered per server-side poll batch
• Events arrive in chronological order (oldest first within a batch)

Aggregation queries (group by) are rejected with soql_tail_aggregation_unsupported. Tail doesn't make sense for aggregations.

Example stream

:heartbeat

data: {"event_id":"0192abcd-...","ts":"2026-05-16T10:00:00.123Z","severity":"error","event":"player_kick","actor":"admin:Mitch","message":"VAC kick","payload":{"target":"1337"},"bytes_raw":128}

data: {"event_id":"0192abce-...","ts":"2026-05-16T10:00:00.456Z","severity":"error","event":"db_timeout","message":"5s exceeded","payload":{},"bytes_raw":64}

:heartbeat

The org_id and project_id fields are omitted from tail events (they're constant for the session). All other fields match the events response of /query.

Requires logs:read scope.

curl -X POST "https://example.com/query/tail" \  -H "Content-Type: application/json" \  -d '{    "q": "severity >= error AND source == fivem"  }'

"data: {\"event_id\":\"0192abcd-1234-7567-89ab-cdef01234567\",\"ts\":\"2026-05-17T10:00:00.123Z\",\"ingested_at\":\"2026-05-17T10:00:00.456Z\",\"dataset\":\"security\",\"severity\":\"error\",\"event\":\"player_kick\",\"actor\":\"admin:Mitch\",\"source\":\"fivem\",\"message\":\"VAC kick\",\"payload\":{\"target\":\"1337\"},\"bytes_raw\":128}"

{
  "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": "not_found",
    "message": "file not found"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "file not found"
  }
}