Skip to content
FlagSwiftDocs

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/stream for its key's project and environment.
  • The server sends ready when the connection is accepted, change when a flag, release state or a segment its flags use changes, and reset when 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 change a server SDK downloads the configuration with its ETag (an unchanged result is a 304) 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 answers 204 and 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 your environment option).
  • 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#

  1. Turn it on in the SDK

    Set streaming to true (Go: WithStreaming(true), Python: streaming=True, Java: streaming(true)). The SDK opens one connection. Optionally set streamingPollInterval (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 reads connected (see the last step).
  2. Make your proxy pass the stream through

    The server sends X-Accel-Buffering: no for nginx. Other reverse proxies and CDNs must pass text/event-stream through without buffering and must not time out an idle response sooner than the 20-second heartbeat, or changes arrive late.

  3. Change a flag and watch it arrive

    Toggle a flag in the console. The server sends a change event 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.
  4. Read the stream status

    The SDK's status or health report shows streaming as off, connecting, connected or unavailable. Unavailable means the SDK has settled on polling. In the Node SDK it is flags.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.

Request
curl -N "https://flags.example.com/api/v1/evaluation/stream?env=production" \
  -H "Authorization: Bearer $KEY" -H "Accept: text/event-stream"
What you see
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

If streaming is off on the server, the endpoint is missing on an older server, or the key is refused, the SDK settles on polling. Evaluation is never affected by a stream failure.

Good to know#

Mind one connection per client

Every browser tab that streams holds one connection against the key's limit of 100. For a public site with a client key, leave streaming off for pages where a 30-second delay does not matter.
Server setting for operators
VariableDescription
STREAM_ENABLEDDefault on. Set to 0, false, off or no to turn the endpoint off (it then answers 204).
Does streaming change who sees what?
No. The stream says only that something changed. The configuration or evaluation that follows uses the same rules and the same key as polling.
Will the stream wake a sleeping serverless function?
No. A stream needs a long-lived process. In a function that starts per request, leave streaming off and rely on a fresh fetch or a bootstrap.
Do I still need refreshInterval?
Yes. It is the rate used whenever the stream is not connected. Setting it to 0 turns polling off, which also removes your safety net.
How do I know a change was missed?
You will not usually need to. The safety-net poll catches it, and a reconnect always refetches. Each change event also carries a rising id, so a custom reader could notice a gap.

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_connections shows 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.