What is an event stream?
An event stream is an ordered list of things that happened in your account, such as a new message arriving, which an AI agent can read to stay up to date.
In plain words
Picture a conveyor belt of small notes at a sushi bar. Each note says what just happened: a customer wrote in, someone commented, an account needs attention. The notes come in order, and you can pick up from the last one you read.
That place you stopped is called a cursor. Your agent remembers it, and the next time it looks, it asks only for what came after. Nothing is missed and nothing is read twice.
An event stream is useful because an agent has no ears. It cannot hear a phone ring. Without a stream it would have to keep asking, over and over, whether anything is new.
With one, it can simply wait for the next note, or catch up after a nap.
For an owner, this is what lets an agent answer a customer within moments, rather than at the next scheduled check.
It also means a short break in service is no disaster, because the notes wait for your agent in order until it is ready to read them.
How it works in Spaces
The Spaces event stream is at GET /v1/events, and agents on MCP use the wait_for_events tool. It returns at once when something new is waiting, and otherwise waits for the first new event. It never contacts the platform itself.
Events cover new messages, comments, invitations, followers and account status, and are kept for 14 days. A key only sees events for the accounts it may read.
Related terms
- Polling: Polling means checking again and again, on a timer, whether anything new has happened, instead of being told when it does.
- Long polling: Long polling is a way of checking for news where the request waits patiently until something happens, then answers at once.
- Trigger: A trigger is something that happens, such as a customer sending a message, that wakes your AI agent so it can respond straight away.
- Webhook: A webhook is a message one service sends automatically to another's web address the moment something happens, such as a new customer message arriving.
FAQ
How long are events kept?
For 14 days, so an agent that was switched off can catch up when it returns.
Will my agent see events from every account?
Only the accounts its key is allowed to read.
Does reading the stream touch my Instagram or WhatsApp?
No. It reads from Spaces, so it puts no pressure on the platform.
Is the stream the same as a webhook?
They carry the same kind of events. The stream is read by your agent. A webhook is pushed to a web address.
Useful next: Triggers, API reference, Connect your AI agent. Every term: the glossary.