What is a long polling?
Long polling is a way of checking for news where the request waits patiently until something happens, then answers at once.
In plain words
Regular polling is walking to the mailbox every few minutes. Long polling is standing at the mailbox with a coffee. You stay there until the post arrives, then you walk back with it. If nothing comes after a while, you go home and try again.
The trick is that the waiting happens on the service side. Your agent makes one request and the service holds it open. The moment a new event lands, the answer goes out. That feels almost instant, yet needs no special set-up on your side.
It is helpful for AI agents in particular. Many chat apps cannot receive a message pushed to them, but they can make a request and wait for the reply. Long polling fits that shape neatly.
There is always a time limit on the wait. When it runs out, the request returns empty and the agent simply asks again. For you, the result is simple.
Your agent can sit ready and answer a customer within moments, without you setting anything up or keeping a window open yourself.
How it works in Spaces
The Spaces wait_for_events tool and GET /v1/events with a wait value are long polling. It returns the moment an event arrives, and otherwise waits up to the time asked, at most 50 seconds.
Claude on web, desktop and mobile, ChatGPT and Claude Code do not show push notifications to the model today, so wait_for_events is the instant path there.
Related terms
- Polling: Polling means checking again and again, on a timer, whether anything new has happened, instead of being told when it does.
- 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.
- 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.
- MCP client: An MCP client is the AI app you talk to, such as Claude or ChatGPT, when it connects to an MCP server to use that service's tools.
FAQ
How long will it wait?
Up to the number of seconds your agent asks for, at most 50. The MCP tool waits 30 seconds unless told otherwise.
What happens when the wait runs out?
It returns with no events, and the agent asks again from the same place.
Will my agent miss anything between waits?
No. It passes back its cursor, so the next answer starts right after the last event it saw.
Useful next: Triggers, Agent setup docs, AI agents that work with Spaces. Every term: the glossary.