Skip to main content
A session holds what outlives a single run. A run on its own forgets what it computed the moment it ends. What it writes to its session stays there for the next run, for a person in a playground, and for an agent working through the worker. You create a session once, against a revision of a workflow: with the debugger’s or a playground’s New Session, or a Create Session call. The SDK creates one for a run that names no session, or an alias no session has yet; a session id that does not exist is refused, never created.

​
What a session holds

  • Session objects, typed values each addressed by an alias, including the threads, graphs and files that people, workflows and agents share. Threads & objects covers them.
  • The executions it has hosted, each with the snapshot of the definition it ran and its own event log.
  • The events its activity raises: the session closing or being deleted, an object written or deleted, an item posted to a thread, a batch applied to a graph. Any client can page through them; Session Events lists them.
A session can also carry an alias of your choosing, which works in place of its id wherever a run names its session, in a Create Execution call or a schedule. Nothing requires one.

​
Runs inside a session

An execution starts only while its session is open. It runs under the rules of the session’s blob, whatever definition it names: a definition from another workflow, run by reference, still resolves credentials for whoever started the run and imports only the modules the session’s blob allows, and it writes into this session. Two runs, or a run and a client reading over the API, hand values to each other through the session’s objects. Two limits bound this, both resolved for the session’s blob: workflow.sessions_per_revision caps how many sessions a revision holds, and workflow.executions_per_session how many executions one session holds. Limits has their values and the rest of the catalog.

​
Lifecycle

A new session is open and fully writable. Closing it moves it to closing, stops every execution still running in it, and settles into closed once each one has finished. A closed session is read-only, not hidden: its objects, thread items, graph elements and runs all stay readable, and reopening it returns it to open. Deleting is the other way out, from open, closing or closed. The session moves to deleting, every running execution is stopped and waited on, and only then is anything removed: its objects and everything its threads, graphs and files held, its executions with their snapshots, its events, and the session itself. A deleted session cannot be brought back. Both paths share one rule. The moment a session leaves open, every write is refused: uploading or deleting an object, posting to a thread, changing a graph, starting a run. Nothing new lands while a session closes, and nothing is purged while a run could still write into it. A session belongs to its revision, not to the workflow. Committing the revision closes every session still open on it, the same way a direct close would, and a new revision starts with no sessions at all. In the web app, the debugger lists a revision’s sessions and offers New Session, Close Session, Reopen Session and Delete Session. Session Lifecycle has each transition and its errors.

​
Retention

A finished execution, with its events and data, is kept for 90 days by default, under the workflow.execution_retention_days limit. A daily sweep removes older ones, in an open session or a closed one, and each removal frees a slot under workflow.executions_per_session, so a session a schedule fires into every minute stays below its limit. A session and its objects are never removed by retention. They stay until the session is deleted, and deleting it removes everything in it at once. Retention covers the rules.