The Events API provides event push as well as historical queries via SSE (server sent events).
You can listen to events related to trade updates. Most market trades sent during market hours are filled instantly; you can listen to limit order updates through this endpoint.
Historical events are streamed immediately if queried, and updates are pushed as events occur.
Query Params Rules:
since_idcan’t be used at the same time
since_idnot specified this will not return any historic data
until_idreached stream will end (status 200)
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
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 correcting in OAS-3.
Legacy trade events API
The legacy trade events API is available for compatibility reasons at:
Broker partners are recommended to upgrade to the /v2beta1/events/trades endpoint, which provides faster event delivery times.
The legacy trade events api works the same way as the new one with the exception of the event_id which is an integer except of an ULID. This results in the request’s since_id and until_id are also being integers. This integer is monotonically increasing over time for events.
These are the events that are the expected results of actions you may have taken by sending API requests.
The meaning of the timestamp field changes for each type; the meanings have been specified here for which types the timestamp field will be present.
new: Sent when an order has been routed to exchanges for execution.
fill: Sent when your order has been completely filled.
timestamp: The time at which the order was filled.
partial_fill: Sent when a number of shares less than the total remaining quantity on your order has been filled.
timestamp: The time at which the shares were filled.
canceled: Sent when your requested cancellation of an order is processed.
timestamp: The time at which the order was canceled.
expired: Sent when an order has reached the end of its lifespan, as determined by the order’s time in force value.
timestamp: The time at which the order expired.
done_for_day: Sent when the order is done executing for the day, and will not receive further updates until the next trading day.
replaced: Sent when your requested replacement of an order is processed.
timestamp: The time at which the order was replaced.
These are events that may rarely be sent due to unexpected circumstances on the exchanges. It is unlikely you will need to design your code around them, but you may still wish to account for the possibility that they will occur.
rejected: Sent when your order has been rejected.
timestamp: The time at which the rejection occurred.
held For multi-leg orders, the secondary orders (stop loss, take profit) will enter this state while waiting to be triggered.
pending_new: Sent when the order has been received by Alpaca and routed to the exchanges, but has not yet been accepted for execution.
stopped: Sent when your order has been stopped, and a trade is guaranteed for the order, usually at a stated price or better, but has not yet occurred.
pending_cancel: Sent when the order is awaiting cancellation. Most cancellations will occur without the order entering this state.
pending_replace: Sent when the order is awaiting replacement.
calculated: Sent when the order has been completed for the day - it is either filled or done_for_day - but remaining settlement calculations are still pending.
suspended: Sent when the order has been suspended and is not eligible for trading.
order_replace_rejected: Sent when the order replace has been rejected.
order_cancel_rejected: Sent when the order cancel has been rejected.