Stream notifications for a single query via Server-Sent Events (SSE).

To follow every query you own over one connection instead, use /queries/stream — see Stream Notifications For All Queries.

Cost

Free.

Auth

Required header:

x-elfa-api-key: <api_key>

Request Example

Path parameter:

• queryId (string)

Response Format (SSE)

id: <outbox-event-uuid>
event: notification
data: {"status":"triggered","title":"...","body":"...","queryId":"<uuid>","timestamp":1743379200000}

status is one of triggered, stopped, ended, or update. The payload also carries the query's execution context when present (executionId, triggerTime, conditionsMet, autoDetails). id is the notification outbox event UUID.

A : keep-alive comment is sent every 15s. Events are live-only — there is no replay, and Last-Event-ID is ignored.

Lifecycle

The request returns 410 when the query is already terminal and its notifications have drained. Once the query reaches a terminal state (triggered, failed, expired, cancelled) and its notifications have been delivered, the stream emits and then closes:

event: end
data: {"code":"QUERY_STREAM_CLOSED","status":"<terminalStatus>","queryId":"<uuid>"}

A recurring query is not terminal — its stream stays open across triggers.

Best practice: deduplicate SSE events by event id and process with a queue-backed worker for reliable agent execution.