# End an avatar session (optional explicit stop)

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

`POST /v1/avatar_sessions/{id}/end`

Ends either kind of API session; for a conversation, `POST
/v1/sessions/{id}/end` with an API key is the same call. It settles `completed` with
`endReason: ended_by_api`, never `failed`.

Stops billing for the session now. **Idempotent**: ending a session that
already ended answers `200` with `alreadyEnded: true`, so the plugin can
call it from every teardown path without checking first. The primary end
signal is the rendering worker's own report when your agent leaves, the
room closes, or you remove the avatar participant — this call is the
fallback for a worker that could not report, and the way to stop paying
for an avatar you are done with while your room stays open. For a
render it does not remove the avatar from your room; remove the
participant yourself (the plugin does so on close). A conversation's room is closed, as by
`POST /v1/sessions/{id}/end`. Acts only on sessions started through
the API (the account's website sessions are `404`), and for an
avatar-scoped key only on its avatar's.

## Parameters

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

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | The session is ended (or already was). | `AvatarSessionEndResponse` |
| `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` |
| `500` | `finalize_failed` — the session could not be settled; retry | `ApiErrorResponse` |
| `503` | `session_unavailable` — the session could not be ended from here right now (its conversation room could not be closed); retry after the `Retry-After` seconds. A retry is safe: ending is idempotent. | `ApiErrorResponse` |

## `200` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sessionId` | string | yes |  |
| `status` | string (`completed`, `failed`) | yes |  |
| `endedAt` | string | no |  |
| `alreadyEnded` | boolean | yes | True when the session was already terminal before this call. |
| `endReason` | string | no | Why the session ended: `ended_by_api` for this call, or the earlier reason when it had already ended (see AvatarSessionStatusResponse.endReason). |