# Retrieve a session (/en/api-reference/api-ref/conversational-ai/platform/retrieve-session)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI API.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-api-v2.txt).


Retrieves the status of a session.

- OpenAPI: /openapi/conversational-ai/rest-api-platform.en.yaml
- Operation ID: retrieve-session
- Method: GET
- Path: /v1/projects/{appid}/sessions/{agent_session_id}
- Endpoint: https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/sessions/{agent_session_id}

## Servers

- https://preview.ai.agora.io/conversational-ai

Starting and stopping a session happen asynchronously. Retrieve the session to follow its `status`. After the session ends, the response includes `stop_ts`.


## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of your project.
- `agent_session_id` (path, required, string) - The ID of the session, returned in `agent_session_id` when you start the session.

## Request body

No request body.

## Responses

### 200

The request was successful. The response body contains the session.

- `agent_session_id` (string) - The ID of the session.
- `agent_name` (string) - The name of the agent that the session runs.
- `status` (string) - The status of the session:

- `IDLE`: The session is idle.
- `STARTING`: The session is starting.
- `RUNNING`: The session is running.
- `STOPPING`: The session is stopping.
- `STOPPED`: The session has ended.
- `FAILED`: The session failed.
  - Allowed: `IDLE` | `STARTING` | `RUNNING` | `STOPPING` | `STOPPED` | `FAILED`
- `start_ts` (integer) - The time the session was created, as a Unix timestamp in seconds.
- `stop_ts` (integer | null | null) - The time the session ended, as a Unix timestamp in seconds. `null` while the session is active.
- `message` (string | null | null) - Additional details about the status, such as a failure diagnosis. `null` when there are none.
### 401

Authentication is missing or invalid. The reason is `InvalidPermission`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### 404

The resource in the path doesn't exist. The reason is `ResourceNotFound`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### default

The request failed. The response body contains the `reason` and `detail` of the failure. For possible reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

## Response examples

### 200

```json
{
  "agent_session_id": "a42ac95tp25py49fc37hp94vm67ht52h",
  "agent_name": "Customer Support Agent",
  "status": "RUNNING",
  "start_ts": 1735035893,
  "stop_ts": null,
  "message": null
}
```