The Events API provides event push as well as historical queries via SSE (server sent events).

This stream is correspondent-scoped and v2-only. A subscriber receives rebalancer events for their own correspondent. Every event_id is a ULID.

You can listen to portfolio status changes, portfolio run creation, and portfolio run status changes.

Historical events are streamed immediately if queried, and updates are pushed as events occur.

Query Params Rules:

• since required if until specified
• since_id required if until_id specified
• since and since_id can't be used at the same time
• until and until_id can't be used at the same time

Behavior:

• if since or since_id not specified this will not return any historic data
• if until or until_id reached stream will end (status 200)
• the Last-Event-Id request header, when present, is used as since_id and takes precedence over the since_id query parameter. Combining it with since returns an error, the same as sending since and since_id together.
• since and until select events by the time encoded in event_id (when the event was emitted), not by at. To resume reliably, use since_id or Last-Event-Id.

Event types

event_type selects the payload:

• portfolio.status_changed carries the portfolio snapshot. Weights and rebalance conditions are included. symbol is always present on a weight and is null for cash.
• run.created and run.status_changed both carry the full run snapshot: id, account_id, portfolio_id, type, initiated_from, status, reason, created_at, updated_at, completed_at, and canceled_at. weights, orders, failed_orders, and skipped_orders are omitted; read them from GET /v1/rebalancing/runs/{run_id}.
• Run status on this stream is QUEUED, IN_PROGRESS, CANCELED, ERROR, TIMEOUT, COMPLETED_ADJUSTED, or COMPLETED_SUCCESS. CANCELED_MID_RUN is not sent.

correspondent is not included in the event JSON.

Note for people using the clients generated from this OAS spec. Currently OAS-3 doesn't have full support for representing SSE style responses from an API, so if you are using a generated client and don't specify a since and until there is a good chance the generated clients will hang waiting for the response to end.

If you require the streaming capabilities we recommend not using the generated clients for this specific usecase until the OAS-3 standards come to a consensus on how to represent this correctly in OAS-3.