> For the full page index, fetch https://echonova.ai/llms.txt # Get a live session Returns the status of a session this API started or any web voice or chat session of the agent. The token is never returned again. Needs the agents:talk scope on the key. ## Endpoint `GET https://api.echonova.ai/v1/agents/{agentId}/sessions/{sessionId}` ## Authentication Keys are created in the portal under Developers, sent as `Authorization: Bearer YOUR_API_KEY`. See [Get an API key](/docs/developers/get-an-api-key). ## Request | Name | In | Type | Required | Limits | Description | | --------- | ---- | ------ | -------- | ------ | ---------------------------------------------- | | agentId | path | string | Yes | | The agent id, as GET /v1/agents returned it. | | sessionId | path | string | Yes | | The session id, as the start call returned it. | ## Responses | Status | Description | | ------ | --------------------- | | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 429 | Too Many Requests | | 500 | Internal Server Error | | 503 | Service Unavailable | | 504 | Gateway Timeout | ## Response A success answers 200 with the envelope `{ data, success, statusCode, errorMessage }`. The `data` fields: | Field | Type | Description | | --------- | ------ | --------------------------------------------------------------------------------------------------------------- | | id | string | The session id; also the conversation id once it ends. | | agentId | string | The agent id. | | channel | string | voice for a room you speak in, chat for a text session. | | status | string | active while it is open; ended after you end it or it finishes; failed or out_of_credits when it stopped early. | | startedAt | string | When it started, as an ISO 8601 date-time. | | endedAt | string | When it ended; null while it is open. | ```json { "data": { "id": "6651a1b2c3d4e5f6a7b8c9d0", "agentId": "6650a1b2c3d4e5f6a7b8c9d0", "channel": "voice", "status": "active", "startedAt": "2026-11-07T10:00:00.000Z", "endedAt": null }, "success": true, "statusCode": 200, "errorMessage": null } ``` ## Errors | Status | errorMessage | When | Fix | | ------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | 400 | Invalid identifier | agentId or sessionId is not a 24-character hexadecimal id. | Use the id exactly as GET /v1/agents returned it. | | 401 | Unauthorized | The Authorization header is missing or is not Bearer ek\_..., no key matches the token, or the key is deleted, disabled or its account is closed. | Send Authorization: Bearer ek\_... with an enabled key from this environment. | | 403 | Subscription not found | The workspace that owns the key has no subscription. | Check the workspace's plan in the portal. | | 403 | Subscription expired or inactive | The subscription is in a state other than active or trial. | Renew the subscription. | | 403 | This API key cannot talk to agents. | The key does not have the agents:talk scope. | Edit the key and give it the agents:talk scope, or use another key. | | 403 | The member who created this API key cannot view agents. | The member who created the key has left the workspace, or no longer has both the View agents and Manage developer API permissions. It is checked on every call. | Give that member both permissions again, or create a key as a member who has them. | | 404 | Agent not found | The agent id is unknown, or the agent belongs to another workspace. | Use an id from GET /v1/agents with a key of the agent's workspace. | | 404 | Session not found | The session id is unknown, is not a live session of this agent (a phone call, for example), or the agent belongs to another workspace. | Use the id the start call returned, with the same agent id. | | 429 | ThrottlerException: Too Many Requests | The key made more than 100 requests to one endpoint in 60 seconds, or one IP address made more than 100 requests to one endpoint in 60 seconds (the IP limit is counted before the key is checked, so it can answer with no key at all); a Retry-After header carries the seconds to wait. | Wait Retry-After seconds, then retry. | | 500 | Something went wrong | An error the API did not classify. | Check the request, then retry after a short wait; contact support if it persists. | | 503 | Database unavailable | A transient outage inside the API. | Retry after a short wait. | | 504 | Database timed out | A transient timeout inside the API. | Retry after a short wait. | ## Code samples :::tabs ```bash title="cURL" curl "https://api.echonova.ai/v1/agents/{agentId}/sessions/{sessionId}" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import requests response = requests.get( "https://api.echonova.ai/v1/agents/{agentId}/sessions/{sessionId}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) print(response.json()) ``` ```javascript const response = await fetch('https://api.echonova.ai/v1/agents/{agentId}/sessions/{sessionId}', { method: 'GET', headers: { Authorization: 'Bearer YOUR_API_KEY', }, }); console.log(await response.json()); ``` :::