Search documentation
karat

+

K

User Documentation ↗
Version 2.0

Get Session State

GET/api/v2/agents/agentSessions/{agentSessionId}/getSessionState
Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Get the state of an Agent session.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:agents-read.

Path parameters

agentSessionId
string

Identifies an Agent session.

Query parameters

consistencyKey
stringoptional

The minimum session state the response must include. If the requested state is not yet available, the result is behind. When omitted, the API returns the latest session state available to the server.

preview
booleanoptional

Enables the use of preview functionality.

Response body

GetStateResponse
union

The result of reading Agent session state.

Hide child attributes

Hide child attributes

behind
objectoptional

The server has not yet observed the requested consistency key. The session may or may not have started. Retry the request after a short delay.

available
objectoptional

The requested state and its session status are available.

Show child attributes

Show child attributes

notReady
objectoptional

The session has not started and cannot be read or accept events yet. Retry after a short delay.

Examples

Request

Copied!
1 2 3 curl \ \t-H "Authorization: Bearer $TOKEN" \ "https://$HOSTNAME/api/v2/agents/agentSessions/3fa85f64-5717-4562-b3fc-2c963f66afa6/getSessionState?preview=true"

Response

Copied!
1 2 3 { "type": "notReady" }

Error responses

Error Name
InvalidConsistencyKeyError CodeINVALID_ARGUMENT
Status Code400
DescriptionThe provided consistency key does not match the expected format.
ParametersconsistencyKey
GetSessionStatePermissionDeniedError CodePERMISSION_DENIED
Status Code403
DescriptionCould not getSessionState the AgentSession.
ParametersagentSessionId
AgentSessionNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe given AgentSession could not be found.
ParametersagentSessionId