Skip to navigation

Get session by ID

Beta

Retrieve a single session by its asset ID, including state, originating channel, agent/model, message count, and cost.

Authentication

X-API-KEYstring
API Key authentication via header

Path parameters

asset_idstringRequired
Unique identifier of the session asset to retrieve

Headers

X-Athena-Session-CredentialstringOptional

Response

Successful Response
created_atdatetime

Timestamp when the session was created (ISO 8601)

idstring

Unique identifier of the session asset (e.g., ‘asset_abc123’)

session_status_v2string

Canonical user-facing session status: idle, active, needs_input, or error

thread_idstring
LangChain thread ID backing this session's message history
updated_atdatetime

Timestamp when the session was last updated (ISO 8601)

agentstring or nullOptional
Agent identity the session ran with, when set
aop_asset_idstring or nullOptional

Source AOP asset identifier for an AOP/workflow run

aop_execution_errorstring or nullOptional
Execution error recorded for a failed AOP run, when present
aop_execution_succeededboolean or nullOptional
Whether the AOP execution completed successfully, when known
app_idstring or nullOptional
Application identifier the session belongs to, when set
collab_agent_idstring or nullOptional

Asset ID of the collab agent the session was created with, when one was bound; null for stock-agent sessions

created_by_idstring or nullOptional
Unique identifier of the user who created this session
failure_reason_v2string or nullOptional

Canonical failure reason for failed runs; null for non-failed runs

is_sub_sessionbooleanOptionalDefaults to false

Whether this is a branched sub-session of another session

is_unreadbooleanOptionalDefaults to false

Whether the session is unread for the calling user: it changed since they last opened it, or they never opened it and it did not originate from the web app

last_message_previewstring or nullOptional

Plain-text preview of the most recent message, when available

modelstring or nullOptional
Model the session ran with, when set
num_messagesinteger or nullOptional
Number of messages in the session, when tracked
parent_session_idstring or nullOptional

Asset ID of the parent session for sub-sessions

run_status_v2string or nullOptional

Canonical latest-run status: scheduled, queued, running, needs_input, completed, failed, or canceled

session_typestring or nullOptional

Kind of session: ‘session’ (chat), ‘video_session’, ‘desktop_session’, or ‘mobile_session’

source_channelstring or nullOptional

Channel the session originated from (e.g., ‘web’, ‘api’, ‘agent_email’, ‘agent_slack’, ‘agent_sms’)

titlestring or nullOptional
Display title of the session
total_cost_usddouble or nullOptional

Total LLM cost of the session in USD, when tracked. Null unless the caller is Athena staff or an owner or manager of the session’s workspace. Already includes the workspace’s LLM cost multiplier, applied once to the provider’s rate; never apply it again. Sessions priced before the in-house token ledger carry their legacy figure, without it. See docs/SESSION_TOKEN_USAGE_AND_TOKEN_COST_GUIDE.md#which-cost-field-do-i-sum.

trigger_typestring or nullOptional

Trigger that started an AOP/workflow run, such as schedule or api

workspace_idstring or nullOptional
Unique identifier of the workspace this session belongs to
statestring or nullOptionalDeprecated

Deprecated legacy execution state. Use session_status_v2, run_status_v2, and failure_reason_v2 for status UI.

Errors

401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error