Streaming events
Following runs live with server-sent events, reconnecting and reading steps.
- Can I see how Cosmos is thinking?You see its messages and tool calls as steps in the event stream. Hidden reasoning isn't returned, though it's billed as output.FAQ
- Can I watch what Cosmos sees in its browser?The stream shows browser actions as tool steps with short arguments and output. Screenshots aren't part of the published API.FAQ
- Does an open event stream use up my rate limit?An open stream counts once, when you open it, however long it runs. Reconnecting counts as a new request.FAQ
- How do I follow a run live with server-sent events?Open GET /v1/runs/{id}/events and read status, step and done events. Any SSE client or a line reader works.How-to
- How do I follow several runs at once?Open one event stream per run (up to 5 runs are in progress per account), or poll each run, keeping an eye on your rate limit.How-to
- How do I read the event stream in JavaScript?Use fetch and read the body as text, splitting events on blank lines. Browser EventSource can't send the auth headers.How-to
- How do I read the event stream in Python?Use requests with stream=True and iter_lines, parse event and data lines, and reconnect with ?after= after a timeout.How-to
- How do I reconnect to a stream without missing or repeating steps?Count the step events you've received and reconnect with ?after= that number. The stream continues from the next step.How-to
- How do I show a run's progress to my own users?Stream events on your server and forward simple progress updates to your app. Never expose your key to the browser.How-to
- My stream ended with an error event. What now?An error event means the stream had to stop, for example because the key was revoked. Check the code, then reconnect if appropriate.Troubleshooting
- My stream works locally but not behind our company proxy. Why?Some proxies buffer or close long-lived connections. Disable buffering for the stream, reconnect with ?after=, or fall back to polling.Troubleshooting
- Should I stream events or poll for the result?Streaming is recommended: one connection replaces dozens of GET calls. If you poll, wait at least 2 seconds between calls.FAQ
- What event types does the run event stream send?status, step, done, timeout and error: what each Agent API stream event means and the data it carries.Reference
- What happens if I open the stream for a run that already finished?The stream is meant to end with a done event carrying the final run, so you get the result. You can also just GET the run.FAQ
- What's inside a step event?A step is a message (text) or a tool call (name, ok, args, output), with an index. Long fields are capped in the stream.Reference
- Why does my event stream stop after 10 minutes?Each stream connection lasts up to 10 minutes and ends with a timeout event. The run continues; reconnect with ?after=.Troubleshooting
- Why is tool output cut short in the stream?Stream steps are capped: text at 4,000 characters, args at 400 and output at 600. Read the full run with GET /v1/runs/{id}.FAQ
Still need help?
Tried the steps above and still stuck? Email us. We usually reply within the first hour, and always within 24 hours. A full support team is with you.
Infrastructure questions, or permanent deletion of your data
infrastructure@clatterlabs.xyzFor deleting your whole account or the data of one service.