Skip to main content

Sessions

Durable, resumable dialogues with an agent — messages, generations, forks and expiry.

Overview​

A session binds one agent to one thread of conversation. Creating it also creates the conversation underneath, so a single call is enough to start talking; the transcript is then read through that conversation, because naturali stores no message bodies of its own.

On top of a bare conversation, a session adds an agent binding, a lifecycle (open / closed / expired), optional auto-generation, inactivity expiry, message debouncing, and forking.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Sessions.

Data Model​

Session​

FieldTypeDescription
idstringSession public ID
agent_idstringAgent public ID, kept after a shared agent is deleted by its owner.
conversation_idstringUnderlying conversation public ID
statusopen | closed | expired
namestring, nullable
actor_idstring, nullablePublic ID of the user actor, or null when the session was created without one
tagsobjectKey-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM iam:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.
auto_generatebooleanWhen true, automatically triggers generation after each user message (if no generation is in progress).
generating_atstring (date-time), nullableTimestamp when the current generation started, or null if not generating.
created_atstring (date-time)
updated_atstring (date-time)
inactivity_ttl_secondsintegerNumber of seconds of inactivity after which the session expires. 0 means the session never expires.
message_delay_secondsinteger, nullableNumber of seconds to wait after the last user message before sending to the LLM. Acts as a debounce: each new message resets the timer. null or absent means no delay (immediate processing).
max_context_messagesinteger, nullableMaximum number of recent conversation messages sent to the model on each generation. Takes precedence over the agent's max_context_messages; null defers to it. A fork keeps its parent's value.
last_activity_atstring (date-time), nullableTimestamp of the last activity on the session (message added or response generated).
forked_from_session_idstring, nullablePublic ID of the session this one was forked from, or null when it was not forked. Also null once that parent is deleted — a fork survives its parent and keeps its own history.
forked_from_positioninteger, nullableThe parent conversation position this session branched after, or null when it is not a fork or was forked at the tip.
usageobjectWhat the session's generations cost: token counts and cost_usd summed across every metered generation dispatched through it. Present on the single-session read; omitted from session and fork list responses. A fork is a session of its own, so it starts at zero rather than inheriting what the history it copied cost — summing usage across a session and its forks therefore never double-counts. Work the platform does around a session without a generation of its own (a memory extraction pass, for instance) is metered on the project, not here.

agent_id is required on create.

Key Concepts​

Posting a message, with or without auto-generation​

POST /v1/projects/{project_id}/sessions/{session_id}/messages saves a user message. If auto_generate is on and nothing is generating, it also starts the run and answers like a generate call; otherwise it returns the saved message and you call POST …/generate yourself. Replay a bad answer posts with it on; Cap spend per end user adds the message and generates in two calls.

idempotency_key on the message body, or the Idempotency-Key header, deduplicates within the session: the same key returns the original message with 200 and starts no second generation — which is what makes a retrying webhook safe. Reusing a key with a different message, document_id or tool_context is 409 IDEMPOTENCY_KEY_REUSED; sending both spellings with different values is 400 VALIDATION_FAILED.

Generation is background by default​

POST …/generate answers 202 Accepted with the turn's generation_id and trace_id once its generation record exists, unless you pass wait=true. A refusal before that record (a closed or expired session, a generation already in progress) is the same error wait=true answers. Poll the generation for the result, or pass stream: true to receive the turn's events as Server-Sent Events until it settles, as on GET /v1/projects/{project_id}/generations/{generation_id}/events (stream: true with wait=false is 400). A session with no message to answer is 400 NO_MESSAGE_TO_ANSWER, and nothing runs. A client-type tool pauses the run with requires_action and a required_action payload; resume it with POST …/tool-outputs, which takes the generation_id and one output per pending call; the resumed turn runs under the authority it started with, held to yours (a resume only narrows). A completed turn is stored right after the last message it read, so a message sent while it ran or waited on tool outputs stays after it.

On a managed provider the model the session's agent would run must carry a price, or the call answers 409 MODEL_NOT_PRICED and generates nothing; a project that owes for usage already served answers 402 INSUFFICIENT_CREDIT until it is topped up. See A managed model must carry a price and A negative balance stops managed generation.

A Free account that has used its plan's monthly runs answers 403 PLAN_LIMIT_REACHED with resource: "runs" here as well, on its own credential too. See A plan's run allowance can stop generation.

This holds however the call arrives: a call to this API or an agent's tool call.

Handing the outputs back with POST /v1/projects/{project_id}/sessions/{session_id}/tool-outputs is what makes the next call, so it answers 402 INSUFFICIENT_CREDIT on the same balance. It needs no price check: the generation it continues cleared one when it started, on the same model. Adding a message is refused the same way only on a session with auto_generate on, where the message starts the generation; otherwise it sits in the session until something generates on it.

Debouncing a chatty user​

message_delay_seconds waits that many seconds after the last user message before calling the model, and each new message resets the timer. Three messages typed in quick succession become one generation with all three in context, instead of three runs racing each other.

What a session cost​

GET /v1/projects/{project_id}/sessions/{session_id} carries a usage roll-up: the token counts and cost_usd of every metered generation dispatched through the session. It answers "what did this conversation cost" without joining the generations log against a rate card.

A fork is a session of its own and starts at zero rather than inheriting what the history it copied cost, so summing usage across a session and its forks never double-counts. Work the platform does around a session without a generation of its own is metered on the project, not here — read GET /v1/projects/{project_id}/usage for the project-wide view.

usage is one number. For the same spend split by day, model or provider, pass the session to the project meter as session_id: see narrowing to one session or one end user; Cap spend per end user splits it by end user. The listing omits usage — reading it per session is a read per session, and a customer's dashboard is better served by one narrowed rollup.

Tool context is write-only​

tool_context set on create, update or fork is a key/value bag forwarded as X-Naturali-Context-<key> headers on every http and mcp tool call in the session; on a message or generate call it applies to that generation only. It may hold credentials, so no read of a session returns it, and closing or expiring the session clears it.

Expiry​

inactivity_ttl_seconds expires a session after a quiet period — status becomes expired and it stops accepting messages. 0 means it never expires.

Forking​

POST …/fork branches a new session from a point in this one's history: same context, different continuation. The fork gets its own conversation whose messages reference the same documents as the parent rather than copying them, so there is one stored copy of the shared history. Omit fork_at_position to branch at the tip, and pass agent_id to have a different agent continue. The fork carries over neither actor_id nor tags, and its response has no tags key; set them on the fork afterwards if the branch should be driven by the same end user. GET …/forks lists one level of lineage: a fork of a fork is listed under its own parent. Replay a bad answer forks at a customer's question so a fixed agent answers it again.

Deleting​

DELETE removes the session, its conversation and their messages. The actor is not deleted, and neither are the generations the session produced — those are records of what happened, not parts of the session.

Examples​

Open a session and send the first message​

SESSION_ID=$(naturali create-session \
--project-id proj_V1StGXR8Z5jdHi6B \
--agent-id agent_V1StGXR8Z5jdHi6B \
--auto-generate true | jq -r .id)

naturali add-session-message \
--project-id proj_V1StGXR8Z5jdHi6B \
--session-id "$SESSION_ID" \
--message "Where is my order?"

Read the transcript​

The transcript lives on the session's conversation:

CONVERSATION_ID=$(naturali get-session \
--project-id proj_V1StGXR8Z5jdHi6B \
--session-id sess_V1StGXR8Z5jdHi6B | jq -r .conversation_id)

naturali list-conversation-messages \
--project-id proj_V1StGXR8Z5jdHi6B \
--conversation-id "$CONVERSATION_ID"

Fork a session to try a different continuation​

naturali fork-session \
--project-id proj_V1StGXR8Z5jdHi6B \
--session-id sess_V1StGXR8Z5jdHi6B \
--fork-at-position 4 \
--name "alternative reply"

Close a session​

naturali update-session \
--project-id proj_V1StGXR8Z5jdHi6B \
--session-id sess_V1StGXR8Z5jdHi6B \
--status closed