Session API

A session is one conversation between a user and an agent. It is created when a conversation transport is opened (see Pipeline Socket) and consists of turns — one user input and the agent’s response to it.

These endpoints read session data after — or during — a conversation. They do not start one.

GET /api/session

List the authenticated user’s sessions, newest first. Requires the consumer or manager role.

Query Parameters

Parameter Required Type Description

limit

No

Integer

Maximum number of sessions to return. Default 20. Must be greater than zero, otherwise 400 is returned.

seekId

No

UUID

Keyset pagination cursor: returns sessions created before the session with this ID. Pass the ID of the last session of the previous page.

Response

An array of Session objects.

GET /api/session/application/{applicationRef}

List the authenticated user’s sessions with one specific agent, newest first. Requires the consumer role.

Path Parameters

Parameter Type Description

applicationRef

String

Agent ref. A revision suffix, if present, is ignored, so sessions across all revisions of the agent are returned.

Query Parameters

Parameter Required Type Description

limit

No

Integer

Maximum number of sessions to return. Default 20; must be greater than zero.

seekId

No

UUID

Keyset pagination cursor, as above.

Response

An array of Session objects.

GET /api/session/{sessionId}

Retrieve one session by ID. Requires the manager role.

Path Parameters

Parameter Type Description

sessionId

UUID

Session identifier.

Response

A single Session object. Takes no query parameters.

GET /api/session/{sessionId}/turn

Retrieve the turns of a session in chronological order. Requires the consumer or manager role.

Path Parameters

Parameter Type Description

sessionId

UUID

Session identifier.

Response

An array of Turn objects — this is the endpoint to use for rendering a conversation transcript after the fact. Takes no query parameters.

GET /api/session/{sessionId}/log/llm

Retrieve the language-model invocation log of a session: prompts, responses, tool calls and token usage per turn. Requires the manager role.

Path Parameters

Parameter Type Description

sessionId

UUID

Session identifier.

Response

An array of log records, one per model invocation, each carrying the invoking component, the model and its parameters, the messages sent, the response, any tool calls with their results, and the token usage. Payloads can be large and are sanitized for sensitive information before being stored. Intended for diagnostics and quality review; takes no query parameters.

Session Object

Field Type Description

id

UUID string

Session identifier. This is the sessionId used when opening a conversation and when polling evaluation status.

created

Timestamp

When the session started.

lastModified

Timestamp

When the session was last written to.

state

String

OPEN (active), ENDED (ended by user or agent), ABANDONED (untouched for too long) or DISCONNECTED (client connection lost without ending the session).

pipelineKey

Object

The pipeline key the session runs under: setupName and contentRef.

agent

Object | null

Snapshot of the agent that served the session: ref, state, revision.

testedAgentRef

String | null

Set when the session was created by an automated test driving another agent.

deviceId

UUID string

Device the session originated from.

userId

UUID string | null

User the session belongs to. null for a fully anonymous session.

projectId, projectRef, tenantId

UUID string / String

Owning project and tenant.

turnCount

Integer

Number of turns recorded.

lastTurnId

UUID string | null

ID of the most recent turn.

summary

String | null

Generated summary of the conversation, when produced.

rating

Object | null

User rating submitted during the session. Polymorphic on type: csat or nps, each with subtype, revision, timestamp and a data object carrying score and comment.

sensory

Object | null

Environment data reported by the device during the session.

attributes

Object

Arbitrary key/value attributes set on the session by the client (#session-attribute:) or by the agent.

multimodalActions

Object

Per-ref statistics about multimodal interactions shown during the session: executed (parameter sets with counts) and actions (action name to count).

userEmotionalSet, agentEmotionalSet, blendedEmotionalSet

Object

Emotional expression sets tracked for the user, the agent and their blend: happiness, sadness, fear, disgust, anger, surprise, other and lastUpdated.

userEngagement, userEmpowerment, taskCompletion, interactionStyleMatching, buildRelationship, purposeCompletion, businessProcess

Integer | null

Conversation scores produced by evaluation, when configured for the agent.

evaluationResultsState

String

NOT_READY, FINISHED, NO_EVALS or FAILED. See Evaluation API.

hasUserFacingEvals

Boolean | null

Whether this session produces evaluation results meant to be shown to the user.

testMode

Boolean

Session was created with testMode=true and is excluded from production analytics.

trackingRef

String | null

Caller-supplied tracking reference, used to correlate a session with an external record.

userAgent

String | null

User-Agent of the client that opened the session.

traceId, spanId

String | null

Distributed tracing correlation, when the client supplied it.

generationId

UUID string | null

Generation the session belongs to, used to group re-runs.

Example

A completed session with every optional field populated — a csat rating, emotional sets, evaluation scores and client-set attributes:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created": "2026-09-09T14:22:41.118Z",
  "lastModified": "2026-09-09T14:31:02.904Z",
  "state": "ENDED",
  "pipelineKey": { "setupName": "agent", "contentRef": "acme-support" },
  "agent": { "ref": "acme-support", "state": "Published", "revision": 5 },
  "testedAgentRef": null,
  "deviceId": "9b1c2d3e-4f50-4617-8829-9a0b1c2d3e4f",
  "userId": "5c8a0f12-7d34-4e56-9a1b-2c3d4e5f6a7b",
  "projectId": "8e29b3d1-6a4f-4c2e-9d70-1f2a3b4c5d6e",
  "projectRef": "acme",
  "tenantId": "1a2b3c4d-5e6f-4708-8912-a3b4c5d6e7f8",
  "turnCount": 7,
  "lastTurnId": "c3a9d1ef-2d3c-4c9f-9b5f-0e8a2b7d4f21",
  "generationId": null,
  "summary": "The user rescheduled an appointment and asked about parking.",
  "rating": {
    "type": "csat",
    "subtype": null,
    "revision": 1,
    "timestamp": "2026-09-09T14:30:58.220Z",
    "data": { "score": 5, "comment": "Quick and clear." }
  },
  "sensory": null,
  "attributes": { "name": "Alex Novak", "email": "alex@example.com", "campaign": "autumn" },
  "multimodalActions": {
    "parking-map": {
      "executed": [ { "parameters": ["level-2"], "count": 1 } ],
      "actions": { "shown": 1, "dismissed": 1 }
    }
  },
  "userEmotionalSet": {
    "happiness": 0.42, "sadness": 0.0, "fear": 0.0, "disgust": 0.0,
    "anger": 0.0, "surprise": 0.11, "other": 0.05,
    "lastUpdated": "2026-09-09T14:30:41.002Z"
  },
  "agentEmotionalSet": {
    "happiness": 0.55, "sadness": 0.0, "fear": 0.0, "disgust": 0.0,
    "anger": 0.0, "surprise": 0.0, "other": 0.0,
    "lastUpdated": "2026-09-09T14:30:41.002Z"
  },
  "blendedEmotionalSet": {
    "happiness": 0.48, "sadness": 0.0, "fear": 0.0, "disgust": 0.0,
    "anger": 0.0, "surprise": 0.05, "other": 0.02,
    "lastUpdated": "2026-09-09T14:30:41.002Z"
  },
  "userEngagement": 7,
  "userEmpowerment": 6,
  "taskCompletion": 10,
  "interactionStyleMatching": 8,
  "buildRelationship": 6,
  "purposeCompletion": 9,
  "businessProcess": 8,
  "evaluationResultsState": "FINISHED",
  "hasUserFacingEvals": true,
  "testMode": false,
  "trackingRef": "crm-88213",
  "userAgent": "PromethistClient/1.4.2 (iOS 26.0)",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7"
}

An anonymous session in progress has userId: null, state: "OPEN", empty attributes, null scores and evaluationResultsState: "NOT_READY".

Turn Object

Field Type Description

id

UUID string

Turn identifier. Matches the turnId carried by output elements during the conversation.

created

Timestamp

When the turn started.

sessionId

UUID string

Session this turn belongs to.

userId

UUID string

User the turn belongs to.

locale

String

Locale the turn was conducted in.

pipelineKey

Object

Pipeline key in effect for the turn.

input

Array of strings

Raw input elements received from the client during the turn, in wire form.

output

Array of strings

Raw output elements emitted during the turn, in wire form (including # commands).

transcript

Object | null

Final recognized user utterance of the turn.

response

String

Convenience field: the agent’s textual response, i.e. output with all # command entries removed.

log

Object | null

Turn timing log: lastInterimTranscript, finalTranscript, firstTextResponse, lastTextResponse, firstAudioResponse, lastAudioResponse. Used for latency analysis; any of them may be null.

scopeName

String | null

Memory scope the turn was executed in.

generationId

UUID string | null

Generation the turn belongs to.

tenantId

UUID string | null

Owning tenant.

testMode

Boolean

Whether the turn was recorded in test mode.

Example

{
  "id": "c3a9d1ef-2d3c-4c9f-9b5f-0e8a2b7d4f21",
  "created": "2026-09-09T14:30:31.004Z",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "userId": "5c8a0f12-7d34-4e56-9a1b-2c3d4e5f6a7b",
  "tenantId": "1a2b3c4d-5e6f-4708-8912-a3b4c5d6e7f8",
  "locale": "en-US",
  "pipelineKey": { "setupName": "agent", "contentRef": "acme-support" },
  "scopeName": "application",
  "generationId": null,
  "input": ["Can I park there?"],
  "output": [
    "#transcript:text=Can I park there?&isInterim=false",
    "Yes, parking is included on level 2.",
    "#exit"
  ],
  "transcript": { "text": "Can I park there?" },
  "response": "Yes, parking is included on level 2.",
  "log": {
    "lastInterimTranscript": "2026-09-09T14:30:31.612Z",
    "finalTranscript": "2026-09-09T14:30:32.004Z",
    "firstTextResponse": "2026-09-09T14:30:32.590Z",
    "lastTextResponse": "2026-09-09T14:30:33.118Z",
    "firstAudioResponse": "2026-09-09T14:30:32.744Z",
    "lastAudioResponse": "2026-09-09T14:30:34.902Z"
  },
  "testMode": false
}