Plotly Streaming API

Basic streaming concepts

Streaming has been added as an additional API layer on top of the REST API. Therefore you follow the steps for making a REST API plot request to instantiate a base plot with your desired layout, style and mapping of streaming tokens to data arrays. This is accomplished by following the documentation for the REST API with the addition of adding tokens into the data object.
  "x": [],
  "y": [],
  "type": "scatter",
  "mode": "markers",
  "stream": {
      "token": "xxxyyyxxxi",
      "maxpoints": 500
Once this has successfully been posted you are ready to begin streaming to the streaming endpoint, To match your data stream to the correct data object in the initialized plot attach a token to the HTTP headers sent to the streaming endpoint.
headers = {"plotly-streamtoken": "xxxyyyxxxi"}
Once the stream has been connected over http, write to the request stream with newline separated JSON.
httpRequestSocket.write('{ "x": 3, "y": 1 }\n')
The newline is extremely important. Without this delimiter the Streaming Endpoint will not delineate your data, and will terminate the stream. You can send multiple streams to the same plot by nesting stream tokens within the corresponding data trace object. Similarly you can use the same token for multiple traces in a plot (they will show the same stream, so this is useful only in when using subplots).


To connect to the Streaming API, form an HTTP request and write to the request for as long as you want to maintain the stream. Our streaming cluster will hold the connection open indefinitely, barring server-side error, excessive client-side lag, network hiccups, routine server maintenance or duplicate streams using the same token. The method to form an HTTP request and write newline separated data will be different for every language or framework, so consult the documentation for the HTTP library you are using. We have provided example Python and Nodejs documentation. Some HTTP client libraries form a single request body which is sent to the server when the request is closed. These clients will not work for accessing the Streaming API. You must use an HTTP client that will allow writing response data incrementally.


Plotly will close a streaming connection for the following reasons:

  • A client establishes additional streams using the same stream token. When this occurs, the oldest connection will be terminated. This means you have to be careful not to run two reconnecting clients in parallel with the same credentials, or else they will take turns disconnecting each other.
  • A client stops writing data for a time period longer than a minute. If a minute passes without receiving any data from the client the stream connection will be closed. (A connection can be maintained by writing a heartbeat within the 60 second window, a heartbeat is simply a newline).
  • A streaming server is restarted. This is usually related to a code deploy and is not very frequent.


Once an established connection drops, attempt to reconnect immediately. If the reconnect fails, slow down your reconnect attempts according to the type of error experienced:

  • Back off linearly for TCP/IP level network errors. These problems are generally temporary and tend to clear quickly. Increase the delay in reconnects by 250ms each attempt, up to 16 seconds.
  • Back off exponentially for HTTP errors for which reconnecting would be appropriate. Start with a 5 second wait, doubling each attempt, up to 320 seconds.

Data Loss and Write Speed

  • Incoming data should not be written faster than 50ms. We throttle incoming JSON objects at 50ms. While there is a buffer queue to absorb changes in the data rate, continuously sending data faster than 50ms will result in data loss.
  • You must send data every minute otherwise we will consider the stream stale and destroy it. If your data comes in a slower rate send a heartbeat to let the streaming server know it is still active. A heartbeat is simply a newline "\n" written within the 60 second window.

Connection Stability

Repeatedly opening and closing a connection (churn) wastes server resources. Keep your connections as stable and long-lived as possible.

HTTP Error Codes

Most error codes are returned with a string with additional details. For all codes greater than 200, clients should wait before attempting another connection. See the Connecting section, above.
"200": "healthy endpoint disconnect"
, "308": "stream had ended"
, "400": "invalid or malformed request syntax"
, "403": "stream token no longer associated with this plot"
, "404": "streamtoken not registered or valid"
, "405": "bad request method: use POST for streaming"
, "406": "bad request header: missing 'plotly-streamtoken'"
, "408": "timeout on active data"
, "422": "json parse error: please stream newline seperated JSON"
, "423": "connection limit associated with this token has been reached"
, "449": "stream content has changed, reloading clients"
, "500": "internal server error"
, "503": "internal database error"
, "520": "error in request stream"