Skip to main content
Portal

Stream Notifications

GET 
/v2/auto/queries/:queryId/stream
Plan Access
All plans, billed per query in credits
Data Recency
Continuous evaluation against live data
Rate Limit
60 to 120 RPM by plan

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.

Request​

Responses​

SSE stream established (text/event-stream)