Spaces

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

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.