> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt > Use this file to discover all available pages before exploring further. # Read a session > Get a session by its session ID (user-provided string identifier). A session is identified by sessionId AND userId together — the same sessionId can exist once per end user in a project — so reading a session that belongs to a channel end user requires that user's id in the userId query parameter. Omitting it reads the session stored under the empty user id, which is where every in-process caller's session (workflows, subagents, the dev UI) lives. Content derived from the conversation context is never returned: an llm_call event's promptBuild carries the facts of the system prompt build (timings, failure, which prompt was sent, each token's key, syntax, lifetime and error code) but not the system prompt, the tokens as written or their values, and the state carries no prompt values. ## OpenAPI ````yaml https://api-trial.cognigy.ai/swagger/openapi.json get /agentsessions/{sessionId} openapi: 3.0.3 info: contact: email: support@example.com name: API Support description: API for managing agents and related resources license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html termsOfService: http://swagger.io/terms/ title: Agents API version: '1.0' servers: - url: https://api-trial.cognigy.ai/v1 security: - ApiKey: [] tags: - name: Agents - name: Brand personas - name: Tools - name: Built-in tools - name: Skills - name: Built-in skills - name: MCP servers - name: Tool references paths: /agentsessions/{sessionId}: get: tags: - agentsessions summary: Read a session description: >- Get a session by its session ID (user-provided string identifier). A session is identified by sessionId AND userId together — the same sessionId can exist once per end user in a project — so reading a session that belongs to a channel end user requires that user's id in the userId query parameter. Omitting it reads the session stored under the empty user id, which is where every in-process caller's session (workflows, subagents, the dev UI) lives. Content derived from the conversation context is never returned: an llm_call event's promptBuild carries the facts of the system prompt build (timings, failure, which prompt was sent, each token's key, syntax, lifetime and error code) but not the system prompt, the tokens as written or their values, and the state carries no prompt values. parameters: - description: The unique identifier for the session. in: path name: sessionId required: true schema: type: string - description: The unique identifier for the project to scope the request to. in: query name: projectId required: true schema: type: string - description: >- The unique identifier for the channel end user to scope the request to. If you omit it, the default is the empty user. in: query name: userId schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/internal_sessions.SessionDetailResponse' description: OK '400': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest description: Invalid parameters '403': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden description: Access denied '404': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailNotFound description: Session not found '500': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError description: Internal server error components: schemas: internal_sessions.SessionDetailResponse: properties: agentReferenceId: type: string createdAt: type: integer events: items: $ref: '#/components/schemas/internal_sessions.EventResponse' type: array id: example: 507f1f77bcf86cd799439011 type: string lastUpdatedAt: type: integer organisationId: example: 507f1f77bcf86cd799439011 type: string projectId: example: 507f1f77bcf86cd799439011 type: string sessionId: type: string state: allOf: - $ref: '#/components/schemas/internal_sessions.SessionState' description: >- State is the typed session state. json omitempty on SessionState's fields means present-but-empty members (e.g. an empty loadedSkills slice) are omitted; fresh sessions serialize as "state":{}. runtimeContext and runtimeContextExpiresAt are never returned: the runtimeContext is the conversation's Flow context, which can hold secret-bearing values (see toSessionDetailResponse). TODO(follow-up 390): add runtimeContext back to this response once redaction of its values exists. state.promptValues is never returned either: the values are derived from the conversation context, and its json:"-" tag keeps it out (state.go). Return it together with the runtimeContext (follow-up 390). state.handoff.values is redacted too: withoutInternalHandoverValues (below) strips the Value of any entry whose visibility is not prompt-visible before this DTO is built, fail-closed on an unrecognised tier. userId: description: >- UserId is the channel end user this session belongs to — see the same field on SessionItem. type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest: properties: detail: example: request body validation failed type: string errors: items: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.FieldError type: array instance: example: /v1/{resource} type: string status: example: 400 type: integer title: example: Bad Request type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden: properties: detail: example: 'access denied: insufficient permissions' type: string instance: example: /v1/{resource}/{id} type: string status: example: 403 type: integer title: example: Forbidden type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailNotFound: properties: detail: example: the requested resource does not exist type: string instance: example: /v1/{resource}/{id} type: string status: example: 404 type: integer title: example: Not Found type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError: properties: detail: example: internal server error type: string instance: example: /v1/{resource} type: string status: example: 500 type: integer title: example: Internal Server Error type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object internal_sessions.EventResponse: properties: arguments: additionalProperties: {} type: object author: $ref: '#/components/schemas/internal_sessions.EventAuthor' cacheTokens: $ref: '#/components/schemas/internal_sessions.CacheTokens' callId: description: function_call fields type: string completionTokens: type: integer configSetErrors: description: >- ConfigSetErrors lists the config-sets attempted and FAILED, in attempt order. Non-empty does not mean the call failed (a fallback-rescued call carries the primary's failure here), and its length is not a retry count. items: $ref: '#/components/schemas/internal_sessions.ConfigSetError' type: array configSetId: type: string content: type: string cumulativeUsage: allOf: - $ref: '#/components/schemas/internal_sessions.UsageTotals' description: >- CumulativeUsage is the per-session running total as of (and including) this LLM call. Populated only on llm_call events. deploymentLabel: type: string durationMs: description: >- telemetry fields — set on function_call_output (DurationMs only) and llm_call (all four). ReasoningTokens is zero on non-reasoning models; frontends should treat zero as "not applicable". type: integer errorCode: type: integer errorMessage: type: string errorReason: type: string fallback: $ref: '#/components/schemas/internal_sessions.FallbackInfo' fallbackActive: type: boolean finishReason: description: >- --- LLM Gateway metadata (llm_call only) --------------------------------- Mirrors the fields on the gRPC llm_call TurnEvent so a session read back over REST renders identically to the live stream. This DTO is an explicit allow-list, so a field added to sessions.Event does NOT appear here automatically — it has to be added in both places or replay silently loses it. Pointers preserve presence: an unreported field must be absent from the JSON, not serialised as a zero. type: string id: type: string interTokenLatencyMs: type: number itemType: $ref: '#/components/schemas/internal_sessions.ItemType' name: type: string output: description: function_call_output fields type: string promptBuild: allOf: - $ref: '#/components/schemas/internal_sessions.PromptBuildResponse' description: >- PromptBuild describes the build of the call's system prompt: whether the agent has a custom prompt, how long the build took, whether it failed and why, what was sent instead, which prompt the call got, and its tokens by count. Populated only on llm_call events. The prompt itself, the tokens' texts and values and a per-token list are never returned, nor stored (see PromptBuildResponse). promptTokens: type: integer providerStatusCode: description: >- ProviderStatusCode disambiguates ErrorCode: present means ErrorCode is the provider's status, absent means it is the gateway's own. type: integer rawFinishReason: type: string reasoningTokens: type: integer retryCount: type: integer role: allOf: - $ref: '#/components/schemas/internal_sessions.EventRole' description: message fields timePerOutputTokenMs: type: number timeToFirstTokenMs: type: integer timestamp: type: string tokensPerSecond: type: number toolOrigin: allOf: - $ref: '#/components/schemas/internal_sessions.ToolOrigin' description: >- ToolOrigin classifies the tool/skill backing this event. Populated on function_call and function_call_output events; empty otherwise or when origin could not be resolved. See sessions.ToolOrigin for valid values. totalLatencyMs: type: integer totalTokens: type: integer type: $ref: '#/components/schemas/internal_sessions.EventType' type: object internal_sessions.SessionState: properties: handoff: $ref: '#/components/schemas/internal_sessions.HandoffState' loadedSkills: items: type: string type: array usageTotals: $ref: '#/components/schemas/internal_sessions.UsageTotals' voiceAgents: description: >- VoiceAgents are the agents a V2V BuildVoiceSession opened a realtime segment for in this session. ExecuteTool and AppendTranscript act only for an agent listed here, so they cannot write into a session no voice segment of that agent opened. items: type: string type: array type: object github_com_cognigy_ai-agents-v2_internal_middleware.FieldError: properties: field: type: string message: type: string type: object internal_sessions.EventAuthor: properties: id: type: string name: type: string type: object internal_sessions.CacheTokens: properties: readTokens: type: integer uncachedTokens: type: integer writeTokens: type: integer type: object internal_sessions.ConfigSetError: properties: configSetId: description: >- ConfigSetId is the config-set that was attempted. On a failed call this is the only record of which config-set was tried at all, since DeploymentLabel and ConfigSetId describe the deployment that SUCCEEDED. type: string errorCode: description: >- ErrorCode is the gateway's stable error class for this attempt, from a small closed set. Frequently absent — the gateway assigns one on only a few branches — which is fine because StatusCode is always there. type: string errorLabel: description: >- ErrorLabel is the human-readable description of this attempt's failure. Absent when the turn set disableSensitiveLogging: it is the provider's own message verbatim and can echo request content. Capped at 512 runes, like ErrorMessage. type: string modelName: description: >- ModelName is the model identifier of the attempted deployment. Together with Provider it is a failed attempt's equivalent of DeploymentLabel. type: string provider: description: Provider is the LLM provider of the attempted deployment. type: string providerStatusCode: description: >- ProviderStatusCode is the provider's own HTTP status for this attempt, when it answered with one. Absent when the failure never reached it. type: integer statusCode: description: |- StatusCode is the HTTP status the GATEWAY assigned to this attempt's failure. Always populated. type: integer type: object internal_sessions.UsageTotals: properties: callCount: type: integer completionTokens: type: integer promptTokens: type: integer reasoningTokens: type: integer type: object internal_sessions.FallbackInfo: properties: fallbackConfigSetId: type: string fallbackDeploymentLabel: type: string fallbackReason: type: string primaryConfigSetId: type: string primaryDeploymentLabel: type: string type: object internal_sessions.ItemType: enum: - message - function_call - function_call_output - llm_call type: string x-enum-varnames: - ItemTypeMessage - ItemTypeFunctionCall - ItemTypeFunctionCallOutput - ItemTypeLLMCall internal_sessions.PromptBuildResponse: properties: customPrompt: description: |- CustomPrompt is true when the agent has a custom system prompt in effect; false on a builtin prompt. type: boolean dataTokens: description: DataTokens is the number of data tokens. type: integer durationMs: description: |- DurationMs is the wall-clock time of the build, in milliseconds with sub-millisecond precision. type: number errorsByCode: additionalProperties: type: integer description: |- ErrorsByCode counts the expressions that rendered empty because of a script error, by vm4 error code. Absent when there were none. type: object evaluated: description: Evaluated is the number of tokens this build produced a value for. type: integer evaluationMs: description: >- EvaluationMs is the time of the build's vm4 batch, in milliseconds; absent when no CognigyScript expression was due. When a failed custom build fell back to the default prompt, the time of both batches. type: number failed: description: >- Failed is true when the system prompt build failed (a custom build, or the CognigyScript of the agent's fields on a default prompt). type: boolean failureCause: description: |- FailureCause says why: timeout, budget, slot_wait, vm4_unavailable, reply, crash, too_large or empty. Only when Failed. enum: - timeout - budget - slot_wait - vm4_unavailable - reply - crash - too_large - empty type: string fallbackPrompt: description: |- FallbackPrompt is the prompt sent instead: "default". Only when FellBack. enum: - default type: string fellBack: description: >- FellBack is true when a prompt other than the built custom prompt was sent because the build failed; only with a custom prompt in effect. type: boolean reused: description: Reused is the number of tokens whose kept value was reused. type: integer scriptTokens: description: |- ScriptTokens is the number of CognigyScript tokens of the custom prompt build. The counts are all zero without a custom prompt, without tokens, or after a failed build. type: integer sentPrompt: description: |- SentPrompt is which prompt the call got: custom, default or builtin (a call with a prompt of its own, the grounding decline). enum: - custom - default - builtin type: string type: object internal_sessions.EventRole: enum: - user - assistant - system - developer type: string x-enum-varnames: - RoleUser - RoleAssistant - RoleSystem - RoleDeveloper internal_sessions.ToolOrigin: enum: - builtin - custom - mcp type: string x-enum-varnames: - ToolOriginBuiltin - ToolOriginCustom - ToolOriginMCP internal_sessions.EventType: enum: - transcript - trace type: string x-enum-varnames: - EventTypeTranscript - EventTypeTrace internal_sessions.HandoffState: properties: imports: additionalProperties: format: int64 type: integer description: >- Imports is the at-most-once context-import ledger: handoffId → unix ms of the import. Keyed by handoffId, not a bare flag, so a second handoff's context in the same session is never swallowed by the first one's marker. type: object message: description: >- Message is the free-text handover message the transferring flow supplied for the agent. Merged newest-wins across handoffs, like Values. It is exposed on the sessions detail REST API alongside Values (follow-up item 32); acceptable because a handover message is prompt-visible by nature, so it opens no leak class the rendered prompt does not already carry. type: string pendingToolCall: allOf: - $ref: '#/components/schemas/internal_sessions.PendingToolCall' description: >- PendingToolCall is the flow-execution-tool call this agent made and is still waiting on: held here, not in the event log, until the flow's Tool Result node answers it. The call and its answer are then written to the log together, after the flow's transcript, so the history stays a valid call → result sequence. Nil when nothing is held. A later call replaces it; an answer naming another call id is ignored. values: additionalProperties: $ref: '#/components/schemas/internal_sessions.HandoverValue' description: >- Values holds the named values handed over by the flow, keyed by name. Merged newest-wins across handoffs. type: object type: object internal_sessions.PendingToolCall: properties: argumentsJson: description: >- ArgumentsJSON is the call's arguments exactly as the model issued them, as a JSON object. Kept as text rather than a map so the stored value round-trips through BSON unchanged. type: string callId: description: CallID is the model's tool call id; the flow's answer names it. type: string handoffId: description: >- HandoffID is the to-flow routing document the call was handed off with. type: string heldAt: description: HeldAt is when the call was held, unix ms. type: integer name: description: Name is the tool name the model called. type: string toolId: description: ToolID is the tool instance the call resolved to. type: string type: object internal_sessions.HandoverValue: properties: description: description: >- Description is the flow-authored, human-readable note on this value (e.g. "the order the user asked about"). Always disclosed, regardless of Visibility — it describes the entry, not its content. type: string value: description: >- Value is the handed-over payload itself. Withheld (absent from the JSON) on the sessions detail API response when PromptVisible reports false — an absent Value there means the entry exists but was redacted, NOT that nothing was ever handed over; Description and Visibility still appear so a caller can tell the two cases apart. visibility: description: >- Visibility is the disclosure tier the transferring flow declared for this entry: HandoverVisibilityPrompt ("prompt") to render it into the agent's system prompt, HandoverVisibilityInternal ("internal") to keep it out of every prompt. Empty means HandoverVisibilityPrompt (the contract's default). Always disclosed, even when Value is withheld — it is the reason a caller sees no Value, not something to hide alongside it. type: string type: object securitySchemes: ApiKey: description: '[Production] API key for production authentication' in: header name: X-API-Key type: apiKey ````