Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nusomi.com/llms.txt

Use this file to discover all available pages before exploring further.

Events are the structured action stream. Every event is anchored to a frame and to a t_ms offset in its session.

​
Query events

GET /v1/sessions/{id}/events

​
Query

ParamNotes
typeOne or more event types. Repeat for multiple.
t_ms.gte / t_ms.lteTime-range filter.
frame_idRestrict to events on a specific frame.
confidence.gteDrop low-confidence events (e.g. 0.7).
includeframe to embed each event’s frame inline.
orderasc (default) | desc.
limit1–1000. Default 200.
cursorFrom the previous response’s next_cursor.

​
Response

{
  "data": [
    {
      "id": "evt_01HZ...",
      "session_id": "ses_01HZ...",
      "frame_id": "frm_01HZ...",
      "t_ms": 12480,
      "type": "click",
      "payload": {
        "x": 612, "y": 388,
        "target": { "role": "button", "name": "Approve" }
      },
      "confidence": 0.99
    }
  ],
  "next_cursor": "...",
  "has_more": false
}

​
Event types

See frames & events for the full type table. The payload shape is type-discriminated.

​
Emit an event

POST /v1/sessions/{id}/events

{
  "type": "tag",
  "payload": { "name": "submitted_for_approval", "data": {} },
  "t_ms": 14200
}
t_ms is optional. If omitted, the server uses the current wall clock relative to started_at.

​
Batch

POST /v1/sessions/{id}/events

{
  "events": [
    { "type": "click", "payload": { ... }, "t_ms": 12480 },
    { "type": "input_text", "payload": { ... }, "t_ms": 12700 }
  ]
}
Up to 100 events per request. Counts as one request against the rate limit.

​
Stream events

GET /v1/sessions/{id}/events/stream
Accept: text/event-stream
Server-Sent Events. Each line is event: <name> + data: <json>. See streaming for details.

​
Event ordering

Events within a session are totally ordered by (t_ms, evt_id). Two events sharing t_ms are ordered by id. The SDK preserves this order automatically.

​
Confidence

Events extracted from accessibility trees have confidence: 0.99+. Vision-only events (Citrix, RDP, canvas-based UIs) typically land between 0.7 and 0.95. Filter with confidence.gte=0.9 if you want to drop the noisier tail.