agentsessions
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.
GET
/
agentsessions
/
{sessionId}
Read a session
curl --request GET \
--url https://api-trial.cognigy.ai/v1/agentsessions/{sessionId} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"agentReferenceId": "<string>",
"createdAt": 123,
"events": [
{
"arguments": {},
"author": {
"id": "<string>",
"name": "<string>"
},
"cacheTokens": {
"readTokens": 123,
"uncachedTokens": 123,
"writeTokens": 123
},
"callId": "<string>",
"completionTokens": 123,
"configSetErrors": [
{
"configSetId": "<string>",
"errorCode": "<string>",
"errorLabel": "<string>",
"modelName": "<string>",
"provider": "<string>",
"providerStatusCode": 123,
"statusCode": 123
}
],
"configSetId": "<string>",
"content": "<string>",
"cumulativeUsage": {
"callCount": 123,
"completionTokens": 123,
"promptTokens": 123,
"reasoningTokens": 123
},
"deploymentLabel": "<string>",
"durationMs": 123,
"errorCode": 123,
"errorMessage": "<string>",
"errorReason": "<string>",
"fallback": {
"fallbackConfigSetId": "<string>",
"fallbackDeploymentLabel": "<string>",
"fallbackReason": "<string>",
"primaryConfigSetId": "<string>",
"primaryDeploymentLabel": "<string>"
},
"fallbackActive": true,
"finishReason": "<string>",
"id": "<string>",
"interTokenLatencyMs": 123,
"itemType": "message",
"name": "<string>",
"output": "<string>",
"promptBuild": {
"customPrompt": true,
"dataTokens": 123,
"durationMs": 123,
"errorsByCode": {},
"evaluated": 123,
"evaluationMs": 123,
"failed": true,
"failureCause": "timeout",
"fallbackPrompt": "default",
"fellBack": true,
"reused": 123,
"scriptTokens": 123,
"sentPrompt": "custom"
},
"promptTokens": 123,
"providerStatusCode": 123,
"rawFinishReason": "<string>",
"reasoningTokens": 123,
"retryCount": 123,
"role": "user",
"timePerOutputTokenMs": 123,
"timeToFirstTokenMs": 123,
"timestamp": "<string>",
"tokensPerSecond": 123,
"toolOrigin": "builtin",
"totalLatencyMs": 123,
"totalTokens": 123,
"type": "transcript"
}
],
"id": "507f1f77bcf86cd799439011",
"lastUpdatedAt": 123,
"organisationId": "507f1f77bcf86cd799439011",
"projectId": "507f1f77bcf86cd799439011",
"sessionId": "<string>",
"state": {
"handoff": {
"imports": {},
"message": "<string>",
"pendingToolCall": {
"argumentsJson": "<string>",
"callId": "<string>",
"handoffId": "<string>",
"heldAt": 123,
"name": "<string>",
"toolId": "<string>"
},
"values": {}
},
"loadedSkills": [
"<string>"
],
"usageTotals": {
"callCount": 123,
"completionTokens": 123,
"promptTokens": 123,
"reasoningTokens": 123
},
"voiceAgents": [
"<string>"
]
},
"userId": "<string>"
}{
"detail": "request body validation failed",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
],
"instance": "/v1/{resource}",
"status": 400,
"title": "Bad Request",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "access denied: insufficient permissions",
"instance": "/v1/{resource}/{id}",
"status": 403,
"title": "Forbidden",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "the requested resource does not exist",
"instance": "/v1/{resource}/{id}",
"status": 404,
"title": "Not Found",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "internal server error",
"instance": "/v1/{resource}",
"status": 500,
"title": "Internal Server Error",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}Authorizations
[Production] API key for production authentication
Path Parameters
The unique identifier for the session.
Query Parameters
The unique identifier for the project to scope the request to.
The unique identifier for the channel end user to scope the request to. If you omit it, the default is the empty user.
Response
OK
Show child attributes
Show child attributes
Example:
"507f1f77bcf86cd799439011"
Example:
"507f1f77bcf86cd799439011"
Example:
"507f1f77bcf86cd799439011"
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.
Show child attributes
Show child attributes
UserId is the channel end user this session belongs to — see the same field on SessionItem.
⌘I
Read a session
curl --request GET \
--url https://api-trial.cognigy.ai/v1/agentsessions/{sessionId} \
--header 'X-API-Key: <api-key>'import requests
url = "https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-trial.cognigy.ai/v1/agentsessions/{sessionId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"agentReferenceId": "<string>",
"createdAt": 123,
"events": [
{
"arguments": {},
"author": {
"id": "<string>",
"name": "<string>"
},
"cacheTokens": {
"readTokens": 123,
"uncachedTokens": 123,
"writeTokens": 123
},
"callId": "<string>",
"completionTokens": 123,
"configSetErrors": [
{
"configSetId": "<string>",
"errorCode": "<string>",
"errorLabel": "<string>",
"modelName": "<string>",
"provider": "<string>",
"providerStatusCode": 123,
"statusCode": 123
}
],
"configSetId": "<string>",
"content": "<string>",
"cumulativeUsage": {
"callCount": 123,
"completionTokens": 123,
"promptTokens": 123,
"reasoningTokens": 123
},
"deploymentLabel": "<string>",
"durationMs": 123,
"errorCode": 123,
"errorMessage": "<string>",
"errorReason": "<string>",
"fallback": {
"fallbackConfigSetId": "<string>",
"fallbackDeploymentLabel": "<string>",
"fallbackReason": "<string>",
"primaryConfigSetId": "<string>",
"primaryDeploymentLabel": "<string>"
},
"fallbackActive": true,
"finishReason": "<string>",
"id": "<string>",
"interTokenLatencyMs": 123,
"itemType": "message",
"name": "<string>",
"output": "<string>",
"promptBuild": {
"customPrompt": true,
"dataTokens": 123,
"durationMs": 123,
"errorsByCode": {},
"evaluated": 123,
"evaluationMs": 123,
"failed": true,
"failureCause": "timeout",
"fallbackPrompt": "default",
"fellBack": true,
"reused": 123,
"scriptTokens": 123,
"sentPrompt": "custom"
},
"promptTokens": 123,
"providerStatusCode": 123,
"rawFinishReason": "<string>",
"reasoningTokens": 123,
"retryCount": 123,
"role": "user",
"timePerOutputTokenMs": 123,
"timeToFirstTokenMs": 123,
"timestamp": "<string>",
"tokensPerSecond": 123,
"toolOrigin": "builtin",
"totalLatencyMs": 123,
"totalTokens": 123,
"type": "transcript"
}
],
"id": "507f1f77bcf86cd799439011",
"lastUpdatedAt": 123,
"organisationId": "507f1f77bcf86cd799439011",
"projectId": "507f1f77bcf86cd799439011",
"sessionId": "<string>",
"state": {
"handoff": {
"imports": {},
"message": "<string>",
"pendingToolCall": {
"argumentsJson": "<string>",
"callId": "<string>",
"handoffId": "<string>",
"heldAt": 123,
"name": "<string>",
"toolId": "<string>"
},
"values": {}
},
"loadedSkills": [
"<string>"
],
"usageTotals": {
"callCount": 123,
"completionTokens": 123,
"promptTokens": 123,
"reasoningTokens": 123
},
"voiceAgents": [
"<string>"
]
},
"userId": "<string>"
}{
"detail": "request body validation failed",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
],
"instance": "/v1/{resource}",
"status": 400,
"title": "Bad Request",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "access denied: insufficient permissions",
"instance": "/v1/{resource}/{id}",
"status": 403,
"title": "Forbidden",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "the requested resource does not exist",
"instance": "/v1/{resource}/{id}",
"status": 404,
"title": "Not Found",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}{
"detail": "internal server error",
"instance": "/v1/{resource}",
"status": 500,
"title": "Internal Server Error",
"traceId": "api--a4d2f126-bec4-4544-a049-7c0cf08524ed",
"type": "about:blank"
}