Feed protocol and limits

• Level 1, required: accept a connection and send records.
• Level 2, optional: answer replay requests. They fill the platform’s record buffer on a cold start, and they are how a run launched from a date, or over a date window, gets that range.

​

Transports

• WebSocket (wss://). The connection itself is the subscription. The platform sends no greeting; the only frame it can ever send is a replay request (level 2).
• SSE (https://). A GET request with Accept: text/event-stream; the response body is the stream.

​

Records

{"type": "record", "time": 1723456789, "data": {"price": 101.5}}

• time is the record’s timestamp: Unix seconds, UTC. A fractional part is allowed.
• data holds the record fields as one flat object. Names match the dataclass schema declared in the script, and a field of a nested dataclass uses a dotted name, exactly like a CSV column: "data": {"signal": 0.42, "risk.beta": 1.1}. A record that does not match the schema — an unknown field, a missing non-optional field, a nested object, a wrong value type — is dropped at intake, and the stream continues. An optional field may be absent or null.
• An optional id field is read only for the platform’s diagnostics. When present, it must be a JSON string; any other type makes the whole record undecodable, and it is dropped.

• {"type": "heartbeat"} resets the silence clock and does nothing else. Send heartbeats when the gaps between records can exceed the stale_after your consumers declare.
• {"type": "error", "code": "...", "message": "..."} refuses the stream. On a live connection the platform stops serving this feed and subscribed indicators fail with external_feed_gone; use it when you want the platform to stop trying — for example, for a stream that no longer exists. On a short window connection (level 2) it only ends that window request.

data: {"time": 1723456789, "data": {"price": 101.5}}

• The blank line after each event is required: it terminates the event.
• Comment lines (starting with :) count as heartbeats.
• The id: and retry: fields are ignored. The event: field is ignored too, with one exception: event: replay_done (level 2, below).

​

Two rules about timestamps

1. Time does not decrease. Each record’s time is equal to or later than the previous one. A record older than the previous one is dropped.
2. An equal timestamp is a revision. A record with the same time as the previous one replaces it. It is treated as a new version of the same logical record, not as a separate event.

​

Answering replay requests (level 2)

{"replay": {"count": 100}}
{"replay": {"from_time": 1723450000}}
{"replay": {"from_time": 1723450000, "to_time": 1723460000}}

• Timestamps are integer Unix seconds, UTC. from_time is inclusive, to_time is exclusive.
• count asks for the last N records.
• A request with to_time asks for a closed window: send the window, no live part follows.

{"type": "replay_done"}

event: replay_done
data: {}

platform → {"replay": {"from_time": 1723450000, "to_time": 1723460000}}
server   → {"type": "record", "time": 1723451200, "data": {"signal": 0.4}}
server   → {"type": "record", "time": 1723455900, "data": {"signal": 0.7}}
server   → {"type": "replay_done"}
           the connection closes, and no live records follow

• Send what you have; nothing is a valid answer. With nothing to send, send the done frame right away.
• For a window, a done-framed answer is final — an empty answer with a done frame means an empty window, and the platform does not substitute its own buffer. Without a done frame, the records that arrived are used as they are; the platform falls back to its buffer only when nothing usable arrived at all.
• Always finish with the done frame. It is how the platform tells a whole answer from a cut-off one. Without it a warm-up waits out the silence timeout, and a run over a date window ends with an error instead of computing. The platform treats the frame as a signal, not a guarantee: it also ends the replay phase on its own silence timeout, overall deadline and size caps.
• After the done frame, keep the connection open and continue with live records. The exception is a to_time window: answer it, send the done frame, and the connection closes — either side may close it first.
• Records outside the requested bounds, or beyond the requested count, are dropped by the platform.

• The first connection the platform opens to your feed carries a count request. It fills the platform’s own record buffer, which then serves live subscribers without asking you again. A reconnect does not repeat it.
• A launch from a date arrives as a separate short connection with from_time + to_time, where to_time is the present moment. It closes after the answer.
• A run over a date window arrives the same way, carrying the user’s own two dates.
• Warm-up of a launch by history depth is served from the platform’s buffer and never reaches your server.

def on_connection(conn):
    replay = conn.first_frame_or_query_params()   # there may be no request at all
    if replay:
        for record in my_storage.range(replay):
            conn.send(record)
        conn.send({"type": "replay_done"})
        if replay.to_time:                        # a window: answer, then close
            conn.close()
            return
    stream_live(conn)                             # then just send new records

​

Limits