Atmee.aiDocs
APIAPI referenceSession

Get a session

GET
/v1/sessions/{session_id}

Reads the state, end reason and cost of a session started with an API key (POST /v1/sessions or POST /v1/avatar_sessions). It is the same read as GET /v1/avatar_sessions/{id} and never returns room credentials. Website and anonymous sessions are 404.

  • status is pending (starting), active (live), completed (ended normally, including by you) or failed (it never really started; nothing is billed for time it did not run).
  • Once it ended, endReason says why, failureCode names the failure of a failed session, and billedSeconds and chargedMicrocredits say what it cost (100 microcredits = 1 credit).

Authorization

headerX-Api-Key<token>

Your secret API key (sk_atmee_...; older keys start sk_live_), sent as X-Api-Key. Keep it on your server and never send it to a browser.

Path Parameters

session_id*string

The session's id, as POST /v1/sessions returned it.

Formatuuid

Response Body

The session's durable state.

application/json
  1. response
sessionId*string
Formatuuid
status*string

pending starting, active live, completed ran and ended normally (including an end you asked for), failed never really started (see endReason and failureCode).

Value in"pending""active""completed""failed"
kind?string

conversation (POST /v1/sessions) or render (POST /v1/avatar_sessions).

Value in"conversation""render"
avatarJoinedAt?string
Formatdate-time
agentJoinedAt?string

When your agent was seen in the room; billing starts here.

Formatdate-time
userJoinedAt?string

When the visitor (a conversation) or your agent (a render) joined; null when nobody did. Billing runs from the later of this and avatarJoinedAt.

Formatdate-time
endedAt?string
Formatdate-time
endReason?string

Why 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).

Value in"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?string

The failure code of a failed session (e.g. USER_DID_NOT_JOIN, AVATAR_DID_NOT_JOIN); null otherwise.

billingMode?stringDeprecated

Deprecated; always metered for a billed session (see EmbedSessionStartResponse.billingMode).

Value in"reserve""metered"
billedSeconds?integer

Seconds billed (the time both parties were in the room); null while it is live, or when the settlement cannot be read.

chargedMicrocredits?integer

What the session cost once it ended, in microcredits (100 = 1 credit), from the account's balance and the avatar's sponsor pool; null while it is live, or when the settlement cannot be read.

Example Request
curl -X GET 'https://api.atmanity.us/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "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}