Streaming

Resumable real-time event stream (SSE)

Server-Sent Events stream of the live feed envelopes the platform already broadcasts (whale-trade pulses and other public/Pro feed events). Forwards the same backend-owned envelope shape as the internal feed; no provider data is recomputed. Authenticated via the oxi_sk Bearer key like every other /api/v1 endpoint, and limited to a small number of concurrent connections per API key and a cluster-wide ceiling across all keys (HTTP 429 with Retry-After when either cap is exceeded; HTTP 503 with Retry-After if a required Redis service is briefly unavailable). Each delivered frame carries an SSE id from one cluster-shared sequence that remains valid across backend replicas and process restarts. Reconnect with the Last-Event-ID header (or the last_event_id / seq query fallback) to replay the missed window before resuming live. When the requested resume point is older than the retained window, ahead of the current sequence, or separated from live delivery by an uncovered gap, the stream emits a resync marker event (event: resync) instead of silently skipping frames. Idle connections receive periodic ': keep-alive' comment lines. This is a long-lived response: keep the connection open and read frames as they arrive. Authorization is re-checked for as long as the stream is open: every 30 seconds the server re-resolves the key the stream was opened with, so a key that is revoked, expired or rotated, or an account that is deleted, locked or no longer subscribed, ends the stream within 40 seconds (30 seconds plus the credential cache's 10-second bound) with one terminal 'event: error' frame and then closes the connection. The frame's JSON is { type: 'error', error: <the same error object a reconnect is answered with: code, message, doc_url, reason, retry_at>, retry: <boolean> }; retry is false for every credential and account refusal (a reconnect is refused with the same 401, 402, 403 or 423), and true only when the credential store stopped answering (code database_unavailable, after 90 seconds without a confirmed check), in which case reconnect after the error's retry_at with Last-Event-ID set to the frame's id to resume.

get/api/v1/stream

Query parameters

last_event_idstring

Query-string fallback for the Last-Event-ID resume cursor when the client cannot set the request header. Numeric cluster-shared sequence id; non-numeric or absent attaches live with no replay. A future or expired id emits resync.

seqstring

Alias for last_event_id. Numeric cluster-shared sequence id to resume after; non-numeric or absent attaches live with no replay. A future or expired id emits resync.

eventstring

Optional per-connection subscribe-time filter. Comma-separated list of frame wire types (the SSE 'type' discriminator, e.g. WhaleTradesInserted,wallet_grade_changed); a frame passes only when its type is in the set. An unknown token returns HTTP 400 naming the offending value. An empty/all-whitespace value is treated as absent (no constraint). Applied to BOTH the replay window and live frames, and always AFTER the per-subscriber privacy gate, so it can never widen visibility beyond what the key may already see. Combines with condition_id and min_grade as a logical AND; an absent param adds no constraint.

condition_idstring

Optional per-connection subscribe-time filter. Raw provider condition_id or mkt_-prefixed market id (normalized the same way the other v1 market endpoints normalize). A frame passes only when it carries a matching condition_id field; frames that carry no condition_id (e.g. whale-pulse events) are EXCLUDED while this is set. An empty value after normalization returns HTTP 400. Combines with event and min_grade as a logical AND; an absent param adds no constraint.

min_grade'S' | 'A' | 'B' | 'C' | 'D' | 'F'

Optional per-connection subscribe-time filter. A frame passes only when it carries a grade field whose grade is better-or-equal to this minimum (S is best). Frames without a grade (every frame except wallet_grade_changed and LargeTradeInsertedV2) are excluded. An invalid grade returns HTTP 400. Combines with the other filters as a logical AND.

walletstring

Filter LargeTradeInsertedV2 frames to this Polymarket wallet. Other event types have no wallet and are excluded when set. Applied to live and retained Redis frames after privacy checks.

min_sizestring

Filter LargeTradeInsertedV2 frames to trades at or above this USD notional. Positive decimal with at most six places; other event types are excluded when set.

Headers

X-Query-Validation'strict'

Opt into strict query-name validation. The default is compatible: unknown names are ignored and reported in X-Query-Ignored. With strict, an unknown name returns 400 bad_request with error.reason unknown_query_parameter before the handler runs, including when its percent escape is incomplete.

Last-Event-IDstring

Cluster-shared sequence id of the last frame the client successfully processed. The stream replays the strictly-newer retained window before resuming live, even when reconnect routing changes replicas. A future or expired id emits resync. Browser EventSource clients send this automatically on reconnect. Omit to attach live from now.

Response

Open Server-Sent Events stream. The body is an unbounded text/event-stream of frames; each data frame is a JSON feed envelope (with cluster-shared seq, published_at, type, and event-specific fields) and carries an SSE id equal to seq. resync marker frames use event: resync for expired, future, lagged, or otherwise uncovered cursors. A terminal event: error frame (id: <last observed seq>, data: { type: 'error', error: { code, message, ... }, retry: <boolean> }) ends the stream when the key or account it was opened with no longer authorizes it, or when the credential store has not confirmed it within 90 seconds; the connection closes after it.

Changes

Changed in 15 of the 89 revisions of this API.7175136

Sep 23, 20260c27674010652See the full diff
- ○
  added the new optional query request parameter min_size
  new-optional-request-parameter
- ○
  added the new optional query request parameter wallet
  new-optional-request-parameter
Sep 23, 2026ece7a25b7a4477See the full diff
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new freshness_ceiling_unsatisfied enum value to the / response property for the response status
  response-property-enum-value-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
- ○
  added the optional property / to the response with the status
  response-optional-property-added
Sep 23, 20268462acf80f8c7See the full diff
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new export_expired enum value to the / response property for the response status
  response-property-enum-value-added
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Sep 22, 20261c5e270b412471See the full diff
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unknown_query_parameter enum value to the / response property for the response status
  response-property-enum-value-added
- ○
  added the new optional header request parameter X-Query-Validation
  new-optional-request-parameter
Sep 22, 20269958c95371de14See the full diff
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_not_prepared enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new webhook_secret_rotation_overlap_active enum value to the / response property for the response status
  response-property-enum-value-added
Sep 22, 20264bade829e22814See the full diff
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_rate_limited enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new ip_throttled enum value to the / response property for the response status
  response-property-enum-value-added
Sep 22, 20267b5489c2cd3e49See the full diff
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_body enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_path enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new invalid_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new method_not_allowed enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new payload_too_large enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_timeout enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new unsupported_media_type enum value to the / response property for the response status
  response-property-enum-value-added
Sep 21, 20264b70e1891f6114See the full diff
- ●
  added the new insufficient_scope enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new insufficient_scope enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new insufficient_scope enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new insufficient_scope enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new insufficient_scope enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new insufficient_scope enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new insufficient_scope enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new monthly_quota_exceeded enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new monthly_quota_exceeded enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new monthly_quota_exceeded enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new monthly_quota_exceeded enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new monthly_quota_exceeded enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new monthly_quota_exceeded enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new monthly_quota_exceeded enum value to the / response property for the response status
  response-property-enum-value-added
Sep 17, 202605ff312f4bbc7See the full diff
- ●
  added the new api_key_in_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new api_key_in_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new api_key_in_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new api_key_in_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new api_key_in_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new api_key_in_query enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new api_key_in_query enum value to the / response property for the response status
  response-property-enum-value-added
Sep 16, 20261b8c2226ee7b735See the full diff
- ▲
  the response property const value partial_whale_threshold_fills was removed for the status
  response-property-const-removed
- ▲
  the response property const value partial_whale_threshold_fills was removed for the status
  response-property-const-removed
- ▲
  the response property const value partial_whale_threshold_fills was removed for the status
  response-property-const-removed
- ▲
  the response property const value partial_whale_threshold_fills was removed for the status
  response-property-const-removed
- ▲
  the response property const value partial_whale_threshold_fills was removed for the status
  response-property-const-removed
- ▲
  the response property const value partial_whale_threshold_fills was removed for the status
  response-property-const-removed
- ▲
  the response property const value partial_whale_threshold_fills was removed for the status
  response-property-const-removed
- ●
  added the new graded_wallet_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new graded_wallet_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new graded_wallet_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new graded_wallet_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new graded_wallet_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new graded_wallet_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new graded_wallet_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new partial_whale_threshold_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new partial_whale_threshold_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new partial_whale_threshold_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new partial_whale_threshold_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new partial_whale_threshold_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new partial_whale_threshold_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new partial_whale_threshold_fills enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_accounting_unavailable enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_accounting_unavailable enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_accounting_unavailable enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_accounting_unavailable enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_accounting_unavailable enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_accounting_unavailable enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new request_accounting_unavailable enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new sandbox_api_key enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new sandbox_api_key enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new sandbox_api_key enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new sandbox_api_key enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new sandbox_api_key enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new sandbox_api_key enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new sandbox_api_key enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new subscription_inactive enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new subscription_inactive enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new subscription_inactive enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new subscription_inactive enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new subscription_inactive enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new subscription_inactive enum value to the / response property for the response status
  response-property-enum-value-added
- ●
  added the new subscription_inactive enum value to the / response property for the response status
  response-property-enum-value-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history (15 revisions)