Spaces

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

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.