Get changes in real time with streaming
Switch on streaming so a flag change reaches your SDK in about a second instead of at the next poll, and learn what the stream does not promise.
- Time
- About 6 min
- Who can do it
- A developer, plus an operator if the proxy needs changes
- Where
- Your SDK options and the server settings
- You finish with
- Flag changes that reach your app within seconds
What and why#
By default an SDK polls: every 30 seconds it asks the server whether the configuration changed. That is cheap and robust, but it means a toggle can take up to half a minute to reach your app. Streaming closes that gap. The SDK keeps one connection open, and the server sends a tiny message the moment a flag changes. The SDK then fetches the new configuration straight away.
How it works#
- The SDK opens a Server-Sent Events connection to
/api/v1/evaluation/streamfor its key's project and environment. - The server sends
readywhen the connection is accepted,changewhen a flag, release state or a segment its flags use changes, andresetwhen the project's keys or availability change (the stream then closes and the SDK signs in again). A comment line every 20 seconds keeps proxies from closing an idle connection. - The stream carries no flag data. On
changea server SDK downloads the configuration with its ETag (an unchanged result is a304) and a client SDK asks the server to evaluate again. That is why any key type can listen without seeing more than it already could. - Changes that arrive within 100 ms of each other, such as a kill switch over many flags, are sent as one event.
Polling never goes away#
Streaming is a fast path, not a replacement. While a stream is connected, polling slows to a safety net (streamingPollInterval, 5 minutes by default), and it returns to its normal rate when the stream is down. Evaluation is never affected by a stream failure.
Before you start#
- Streaming is off in the SDKs by default. They poll until you turn it on.
- The server side is on by default (
STREAM_ENABLED). If your operator switched it off, the endpoint answers204and SDKs keep polling. - Any key type can listen. A key limited to one environment streams that environment; a project-wide key must say which with
env(SDKs pass yourenvironmentoption). - Streaming is available in the JavaScript, React, Vue, Next.js (client provider), Node, NestJS, Go, Python and Java SDKs. PHP, Laravel, .NET, Flutter and Swift poll, and React Native settles on polling because its fetch cannot read a stream.
Walk through it#
Turn it on in the SDK
Set
streamingto true (Go:WithStreaming(true), Python:streaming=True, Java:streaming(true)). The SDK opens one connection. Optionally setstreamingPollInterval(Python:streaming_poll_interval, in seconds) to change the safety-net poll.ts const flags = await FlagSwift.connect({ apiKey, baseUrl, environment: "production", streaming: true, streamingPollInterval: 300_000, // optional, ms; the default });You should see. Soon after startup the status readsconnected(see the last step).Make your proxy pass the stream through
The server sends
X-Accel-Buffering: nofor nginx. Other reverse proxies and CDNs must passtext/event-streamthrough without buffering and must not time out an idle response sooner than the 20-second heartbeat, or changes arrive late.Change a flag and watch it arrive
Toggle a flag in the console. The server sends a
changeevent and the SDK fetches the new configuration at once. Server SDKs download it with their ETag. Client SDKs ask the server to evaluate again.What happens when you toggle a flag with streaming on. The stream carries no flag data. You should see. Your app shows the new value within a second or two, without waiting for a poll.Read the stream status
The SDK's status or health report shows
streamingasoff,connecting,connectedorunavailable.Unavailablemeans the SDK has settled on polling. In the Node SDK it isflags.getStatus().streaming; in Go,client.Status().Streaming; in Python,get_status().The four stream states an SDK can report.
Listen without an SDK
Useful for checking a proxy. 200 is the stream, 204 means streaming is off on the server, 401 a bad key, and 429 (code STREAM_LIMIT, with Retry-After) means the key or the instance is at its limit. Browsers cannot send an Authorization header with EventSource, which is why the SDKs read the stream with fetch.
curl -N "https://flags.example.com/api/v1/evaluation/stream?env=production" \
-H "Authorization: Bearer $KEY" -H "Accept: text/event-stream"retry: 3000
event: ready
data: {"environment":"production"}
: keep-alive
id: 1
event: change
data: {"at":"2026-10-03T09:30:12.481Z"}What it does and does not promise#
- A change reaches the streams open on the instance that handled it. With several server instances, a change made on another one may not reach your stream. The slower poll picks it up, so worst case is the safety-net interval.
- If the connection drops, the SDK reconnects with backoff and jitter and refetches, so a missed change is caught. The JavaScript SDKs treat a connection that has sent nothing, not even a heartbeat, for 45 seconds as dead and reconnect. Polling returns to its normal rate while it is down.
- Each connection ends after 5 minutes and the SDK reconnects almost at once.
- Streams are capped at 100 per key and 5,000 per instance. Over a cap the server answers
429. - A hidden browser tab or a backgrounded app pauses the SDK and closes the stream. It reopens and refreshes on resume.
- React Native cannot read a response as it arrives, so it settles on polling.
Flags keep working either way
Good to know#
Mind one connection per client
| Variable | Description |
|---|---|
| STREAM_ENABLED | Default on. Set to 0, false, off or no to turn the endpoint off (it then answers 204). |
Does streaming change who sees what?
Will the stream wake a sleeping serverless function?
bootstrap.Do I still need refreshInterval?
How do I know a change was missed?
What to check#
- The status reads connected a moment after startup.
- A toggle in the console shows in your app within a few seconds, without waiting for a poll.
- Behind your proxy the connection stays open. If it reads unavailable, look at buffering and at
STREAM_ENABLED. - With more than one server instance, expect the occasional change to wait for the safety-net poll.
- The Prometheus gauge
flagswift_realtime_connectionsshows open streams on each instance.
If something goes wrong#
Status stays off
Why: The option is not set. Streaming is off by default.
Fix: Set streaming: true (or your SDK's equivalent) and restart.
Status is unavailable and the curl returns 204
Why: The server has STREAM_ENABLED switched off.
Fix: Ask your operator to enable it. Until then the SDK polls and flags still work.
Connected, but changes arrive only every few minutes
Why: A proxy buffers the response, or the change was made on another server instance.
Fix: Disable buffering for text/event-stream. Test with curl -N: you should see : keep-alive lines about every 20 seconds.
429 STREAM_LIMIT
Why: The key or the instance has reached its limit of open streams.
Fix: Close unused clients or share one client per process. The SDK backs off using Retry-After.
Stream drops every five minutes
Why: That is the normal connection lifetime (5 minutes).
Fix: Nothing to fix. The SDK reconnects at once and refetches.