Skip to main content
Session Events are tracking payloads asynchronously generated by Session lifecycle updates rather than intense workflow executions. They primarily inform listeners when data states globally shift within the session memory parameters.

​
Shared Event Format

All session events conform to the following base structure: 
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",   
  "created_at": "2026-05-28T12:00:00.000000Z",
  "type": "event_type_string",
  ... // Dynamic event-specific properties
}

​
Event Types

​
session_object_modified

Fired when a upload_session_object call is made against the Session, modifying semi-persistent object values securely within the active envelope. Extremely useful for reactive applications polling or streaming state updates directly. 
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",   
  "created_at": "2026-05-28T12:00:00.000000Z",
  "type": "session_object_modified",
  "session_object": {
    "alias": "my_stored_configuration_data"
  }
}

​
session_object_deleted

Fired when a delete_session_object call removes a session object from the active session. For thread-typed session objects this also cascades to remove all of the thread’s items. 
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",
  "created_at": "2026-05-28T12:00:00.000000Z",
  "type": "session_object_deleted",
  "session_object": {
    "alias": "my_stored_configuration_data"
  }
}

​
session_thread_item_posted

Fired when a post_session_thread_item call adds an item to a thread session object. Listeners can re-fetch the thread tail via list_session_thread_items using the item_id to anchor created_since. 
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",
  "created_at": "2026-05-28T12:00:00.000000Z",
  "type": "session_thread_item_posted",
  "session_object": {
    "alias": "onboarding_thread",
    "item_id": "uuid-of-the-new-item"
  }
}

​
session_graph_changed

Fired once per apply_session_graph_mutations call, carrying the change delta for the affected graph session object. Each entry in changes identifies one applied operation. 
{
  "id": "uuid-event-id",
  "revision_id": "uuid-workflow-revision",
  "session_id": "uuid-active-session",
  "created_at": "2026-06-06T10:00:01.000000Z",
  "type": "session_graph_changed",
  "session_object": {
    "alias": "task_graph",
    "changes": [
      { "op": "upsert", "element_id": "t1", "type": "vertex", "rev": 4 },
      { "op": "delete", "element_id": "e7", "type": "edge" }
    ]
  }
}
Listeners apply the delta incrementally: remove elements whose op is "delete" from the local cache, then call get_session_graph_elements with the element_id values from the remaining "upsert" entries to fetch their updated state. This avoids refetching the entire graph on each mutation.