Read a session's state, end reason and cost
Reads a session started with an API key (POST /v1/sessions or POST /v1/avatar_sessions): the same read as GET /v1/avatar_sessions/{id}. A start returns how to join; this returns
what happened and what it cost, and never the room credentials.
status is pending (starting), active (live), completed (it
ran and ended normally, including when you ended it) or failed (it
never really started: nobody joined, the avatar did not join, or an
error; nothing is billed for the time it did not run). Once it
ended, endReason says why, failureCode names the failure of a
failed session, and billedSeconds / chargedMicrocredits say what
it cost (100 microcredits = 1 credit). Website and anonymous
sessions are 404.
X-Api-Key<token>Secret embed API key (sk_atmee_...; keys minted before 2026-09
carry sk_live_...), held by the customer's own backend and never
sent to a browser. Format: X-Api-Key: sk_atmee_....
session_id*stringThe session's id, as POST /v1/sessions returned it.
uuidThe session's durable state.
application/json- response
sessionId*stringuuidstatus*stringpending starting, active live, completed ran and ended
normally (including an end you asked for), failed never really
started (see endReason and failureCode).
"pending""active""completed""failed"kind?stringconversation (POST /v1/sessions) or render (POST /v1/avatar_sessions).
"conversation""render"avatarJoinedAt?stringdate-timeagentJoinedAt?stringWhen the worker saw your agent in the room; billing starts here.
date-timeuserJoinedAt?stringWhen the visitor (a conversation) or your agent (a render) joined;
null when nobody did. Billing runs from the later of this and
avatarJoinedAt.
date-timeendedAt?stringdate-timeendReason?stringWhy the session ended; null while it is live. user_left the
visitor left; agent_left your agent left (render); avatar_ended
the avatar ended the call; avatar_removed you removed the avatar
participant (render); max_duration the granted length ran out;
ended_by_api you ended it; room_closed the room closed;
balance_exhausted a metered session ran out of credits or hit
the key's spend cap; no_user_joined nobody joined within the
join window (60 s after the avatar); avatar_did_not_join the
avatar never joined; error anything else (see failureCode).
"user_left""agent_left""avatar_ended""avatar_removed""max_duration""ended_by_api""room_closed""balance_exhausted""no_user_joined""avatar_did_not_join""error"failureCode?stringThe failure code of a failed session (e.g. USER_DID_NOT_JOIN, AVATAR_DID_NOT_JOIN); null otherwise.
billingMode?string"reserve""metered"billedSeconds?integerSeconds billed, as the database settled the session (the time both parties were in the room); null while it is live, or when the settlement cannot be read.
chargedMicrocredits?integerWhat the session cost, once it ended, in microcredits (100 = 1 credit), from the account's balance and the avatar's sponsor pool, as the database settled it; null while it is live, or when the settlement cannot be read.
curl -X GET 'https://api.atmanity.us/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459", "status": "pending", "kind": "conversation", "avatarJoinedAt": "2019-08-24T14:15:22Z", "agentJoinedAt": "2019-08-24T14:15:22Z", "userJoinedAt": "2019-08-24T14:15:22Z", "endedAt": "2019-08-24T14:15:22Z", "endReason": "user_left", "failureCode": "string", "billingMode": "reserve", "billedSeconds": 0, "chargedMicrocredits": 0}