Developers / Agents
List agents
https://api.echonova.ai/v1/agentsLists the agents in this key's workspace, newest change first, paged with offset and limit. Archived agents show only when you ask for status=archived. Needs the agents:read scope on the key.
Headers
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Query parameters
How many items to skip.
How many items to return.
Only agents in this status. Leave it out for every agent that is not archived.
Only agents whose name contains this text.
Response
200 application/json Every response uses this envelope.
The result.
The items on this page.
The agent id.
The agent name.
What the agent is for, or null.
active, or archived once deleted in the portal.
The agent's default voice, or null if it has none.
The voice id, as GET /v1/text-to-speech/voices shows it.
The voice name in English, or null if the voice is gone.
The default voice's dialect, or null.
The language model the agent thinks with.
Who serves the language model.
The model id. Pass it as model to GET /v1/llm/estimate for its price.
How many channels the agent is connected to.
How many conversations the agent has had.
When the agent last changed, as an ISO 8601 date-time.
The total number of items.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. offset on a jobs list is negative.
Fix. Send 0 or more.
When. offset is not a whole number.
Fix. Send an integer.
When. offset on a list is above 10000.
Fix. Send 0 to 10000.
When. limit is below 1.
Fix. Send 1 or more.
When. limit on a list or transcript is above 50.
Fix. Send 1 to 50, and page with offset (or before for a transcript).
When. limit is not a number at all.
Fix. Send an integer from 1 to 50.
When. The body or query carries a field the endpoint does not define.
Fix. Remove the field.
When. status is any other value.
Fix. Send active or archived, or leave it out.
When. q is over 100 characters.
Fix. Send a shorter search.
When. The Authorization header is missing or is not Bearer ek_..., no key matches the token, or the key is deleted, disabled, expired or its account is closed.
Fix. Send Authorization: Bearer ek_... with an enabled key from this environment.
When. The workspace that owns the key has no subscription.
Fix. Check the workspace's plan in the portal.
When. The subscription is in a state other than active or trial.
Fix. Renew the subscription.
When. The key does not have the agents:read scope. Speech and widget ticket access do not give it.
Fix. Edit the key and give it the agents:read scope, or use another key.
When. 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.
Fix. Give that member both permissions again, or create a key as a member who has them.
When. 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.
Fix. Wait Retry-After seconds, then retry.
When. An error the API did not classify.
Fix. Check the request, then retry after a short wait; contact support if it persists.
When. A transient outage inside the API.
Fix. Retry after a short wait.
When. A transient timeout inside the API.
Fix. Retry after a short wait.
curl "https://api.echonova.ai/v1/agents" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": {
"items": [
{
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Sales assistant",
"description": "Answers questions about plans and prices.",
"status": "active",
"voice": {
"id": "6640a1b2c3d4e5f6a7b8c9d0",
"name": "Huda"
},
"dialect": "emirati",
"llm": {
"provider": "openai",
"model": "gpt-4o"
},
"channelsCount": 2,
"sessionsCount": 128,
"updatedAt": "2026-11-01T10:00:00.000Z"
}
],
"total": 1
},
"success": true,
"statusCode": 200,
"errorMessage": null
}