Read an agent's recent event frames
Read the newest frames on the agent's event channel, bounded like its siblings: a read that does not finish within the aggregation deadline, or that fails, returns HTTP 503 saying which. A read the broker refuses is answered 200 with the refusal and, when known, the grant that would allow it. Other methods are refused with 405 and an Allow header naming GET.
cotal_web_session<token>Process-local dashboard session issued by the one-use launch URL.
agent*stringThe agent's id, . with each part in [A-Za-z0-9_], percent-encoded as one URL path component. Any other text is refused with 400.
3 <= length <= 4096limit?integerMaximum requested frames. Absent or empty uses 200. Accepts decimal digits naming a safe integer, including 0; negative, fractional, whitespace-padded and unsafe values are refused.
0 <= value <= 9007199254740991200The page, or the broker's refusal of the read.
application/json- response
The newest frames on the agent's event channel, oldest first, or the broker's refusal of that read.
frames*array<||>more*booleanWhether older frames exist beyond this page.
payloadRead?A payload-only read failure. Metadata frames remain available.
curl -X GET 'http://127.0.0.1:7799/api/agents/local.UACCAXW2KQKIQGMNYJFHWTWZSKA3J2TF7EFCABLCXS5UIZATMT345EWS/events?limit=20'{ "frames": [ { "channel": "string", "contextId": "string", "from": { "id": "string", "name": "string", "role": "string" }, "id": "string", "mentions": [ "string" ], "parts": [ { "kind": "text", "text": "string" } ], "replyTo": "string", "space": "string", "ts": 0 } ], "more": true, "payloadRead": { "status": "timeout", "reason": "string" }}See the HTTP interface overview for authentication and access requirements.
Complete HTTP contract
Endpoint
GET /api/agents/{agent}/eventsRead the newest frames on the agent's event channel, bounded like its siblings: a read that does not finish within the aggregation deadline, or that fails, returns HTTP 503 saying which. A read the broker refuses is answered 200 with the refusal and, when known, the grant that would allow it. Other methods are refused with 405 and an Allow header naming GET.
Parameters
| Name | Location | Required | Schema |
|---|---|---|---|
| agent | path | yes | {"type":"string","minLength":3,"maxLength":4096} |
| limit | query | no | {"type":"integer","minimum":0,"maximum":9007199254740991,"default":200} |
agent: The agent's id, <owner>.<actor> with each part in [A-Za-z0-9_], percent-encoded as one URL path component. Any other text is refused with 400.
limit: Maximum requested frames. Absent or empty uses 200. Accepts decimal digits naming a safe integer, including 0; negative, fractional, whitespace-padded and unsafe values are refused.
Responses
HTTP 200
The page, or the broker's refusal of the read.
Content type: application/json.
{
"$ref": "#/components/schemas/AgentEventsPage"
}HTTP 302
A valid one-use k query token is exchanged for a dashboard session. The response redirects to the same path without its query. A valid existing cookie takes precedence over k.
Location: The requested path without the query string.
Set-Cookie: cotal_web_session=<session>; Path=/; HttpOnly; SameSite=Strict. The default local listener uses HTTP.
HTTP 400
The agent id or the limit was refused.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}HTTP 401
No valid session, an invalid launch token, or a spent launch token. The readiness credential does not authorize these routes.
Content type: application/json.
{
"$ref": "#/components/schemas/AuthenticationError"
}Example:
{
"error": "unauthenticated"
}HTTP 403
Origin is checked before session authentication. An origin outside this listener's allowed origins is refused.
Content type: application/json.
{
"$ref": "#/components/schemas/OriginError"
}Example:
{
"error": "cross-origin"
}HTTP 413
These read routes accept no request body. An announced body is refused before it is read; the connection is closed.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}HTTP 500
The request failed. The body names the failure; a failed read does not terminate the dashboard.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}HTTP 503
The history read failed or did not finish within 8000 ms.
Content type: application/json.
{
"$ref": "#/components/schemas/Error"
}Authentication and access: HTTP interface of the @cotal-ai/web reference implementation. This description covers read operations, readiness metadata and the legacy channel deletion route; it does not establish a separate stable product or Cloud management API. Start the dashboard using the web service preset described in the operator guide. The server defaults to 127.0.0.1:7799; use the host and port configured for your dashboard.
Open the owner-private launch URL once to exchange its k query token for the cotal_web_session cookie. Keep the session on the same host. With the default bind, the permitted browser origins are http://127.0.0.1:<port>, http://localhost:<port> and http://cotal.localhost:<port>. A custom host uses its own HTTP origin. A cross-origin request is refused before session checks. The readiness nonce only opens /api/meta.
Read operations use GET and take no request body. Some read handlers also accept other bodyless methods; this description does not promise a 405 response for them. The native web service is read-only and always refuses channel deletion with 403. Legacy direct dashboard instances can enable deletion; /api/meta reports channelDeleteSupported. Description version 1 identifies this document, not the wire or npm package version.
OpenAPI specification contains the referenced response schemas. Complete Markdown reference.