Developers / Agents

List agents

GET https://api.echonova.ai/v1/agents

Lists 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

Authorization string Required

Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.

Query parameters

offset integer Optional

How many items to skip.

0 to 10000default 0
limit integer Optional

How many items to return.

1 to 50default 20
status string Optional

Only agents in this status. Leave it out for every agent that is not archived.

active or archived
q string Optional

Only agents whose name contains this text.

Up to 100 characters

Response

200 application/json Every response uses this envelope.

data object

The result.

success boolean

true for a successful call.

statusCode integer

Repeats the HTTP status.

errorMessage string or null

null on success.

Errors

Same envelope, with success false and data null. All errors

GET /v1/agents

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
}