# Read a session's state, end reason and cost

URL: https://www.atmee.ai/docs/v2/api/reference/avatar-sessions/getAvatarSession

`GET /v1/avatar_sessions/{id}`

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.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | yes | The avatar session id (`sessionId` from the create response). |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | The session's durable state. | `AvatarSessionStatusResponse` |
| `401` | Missing or invalid API key -- or a user token that is invalid, anonymous, or of a user who may act for no account (invalid_login) | none |
| `403` | `forbidden` — the session belongs to another account \| `avatar_not_allowed` — the session's avatar is not on this key's allow-list \| account_not_allowed (a user token whose X-Account-Id names an account the user may not act for) | `ApiErrorResponse` |
| `404` | `not_found` — no such session, or not one started through the API (a website session) | `ApiErrorResponse` |
| `409` | account_ambiguous -- a user token of a user who may act for several accounts, without an `X-Account-Id` header naming one. | `ApiErrorResponse` |

## `200` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sessionId` | string | yes |  |
| `status` | string (`pending`, `active`, `completed`, `failed`) | yes | `pending` starting, `active` live, `completed` ran and ended normally (including an end you asked for), `failed` never really started (see `endReason` and `failureCode`). |
| `kind` | string (`conversation`, `render`) | no | `conversation` (POST /v1/sessions) or `render` (POST /v1/avatar_sessions). |
| `avatarJoinedAt` | string | no |  |
| `agentJoinedAt` | string | no | When the worker saw your agent in the room; billing starts here. |
| `userJoinedAt` | string | no | When the visitor (a conversation) or your agent (a render) joined; null when nobody did. Billing runs from the later of this and `avatarJoinedAt`. |
| `endedAt` | string | no |  |
| `endReason` | string (`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`) | no | 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`). |
| `failureCode` | string | no | The failure code of a `failed` session (e.g. `USER_DID_NOT_JOIN`, `AVATAR_DID_NOT_JOIN`); null otherwise. |
| `billingMode` | string (`reserve`, `metered`) | no |  |
| `billedSeconds` | integer | no | Seconds 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` | integer | no | What 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. |