Read a session's state, end reason and cost
Reads either kind of API session: a conversation (POST /v1/sessions,
kind: conversation) or a render into your own room (POST /v1/avatar_sessions, kind: render).
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). Billing runs only while both
the avatar and the visitor (or your agent) are in the room:
userJoinedAt and avatarJoinedAt show when each joined.
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_....
id*stringThe avatar session id (sessionId from the create response).
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/avatar_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}Render an avatar into your own LiveKit room (API-key authenticated) POST
Starts an avatar session: the avatar is rendered into a LiveKit room that YOU own, on behalf of YOUR agent — the bring-your-own-agent path the livekit-plugins-atmee plugin uses.
End an avatar session (optional explicit stop) POST
Ends either kind of API session; for a conversation, POST /v1/sessions/{id}/end with an API key is the same call.