Developers / Agents
Get a test run
https://api.echonova.ai/v1/agents/{agentId}/test-runs/{testRunId}Returns one test run of the agent with its status and the chat so far. A scripted run shows running until every message has been answered, then passed, failed or incomplete. 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.
Path parameters
The agent id, as GET /v1/agents returned it.
The test run id, as GET /v1/agents/{agentId}/test-runs returned it.
Response
200 application/json Every response uses this envelope.
The result.
The test run id.
A chat or a voice test.
running, passed, failed, or incomplete: the run stopped before every message was answered, or nobody spoke.
When it started, as an ISO 8601 date-time.
When it ended; absent while running.
The average reply time in milliseconds; absent until the first reply.
The median reply time in milliseconds.
The 95th percentile reply time in milliseconds.
How many turns it took.
How many tool calls the agent made.
How many tools the agent had on.
How many messages a scripted test run was asked to send; absent for other test runs.
The chat so far, oldest first: your messages and the agent replies. Empty until the first turn lands.
The message id.
inbound from the customer, outbound from the agent.
Who wrote it.
The message text.
When it was sent, as an ISO 8601 date-time.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. agentId or testRunId is not a 24-character hexadecimal id.
Fix. Use the ids exactly as GET /v1/agents and the start call returned them.
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 agent id is unknown, or the agent belongs to another workspace.
Fix. Use an id from GET /v1/agents with a key of the agent's workspace.
When. The test run id is unknown, belongs to another agent, or the agent belongs to another workspace.
Fix. Use the id the start call returned, with the same agent id.
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/{agentId}/test-runs/{testRunId}" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": {
"id": "6655a1b2c3d4e5f6a7b8c9d0",
"kind": "chat",
"status": "passed",
"startedAt": "2026-11-03T10:00:00.000Z",
"endedAt": "2026-11-03T10:01:00.000Z",
"latencyMs": 800,
"replyP50Ms": 700,
"replyP95Ms": 1200,
"turns": 4,
"toolsTriggered": 1,
"toolsTotal": 2,
"plannedTurns": 2,
"messages": [
{
"id": "6652a1b2c3d4e5f6a7b8c9d0",
"direction": "inbound",
"sender": "customer",
"text": "How much is the Pro plan?",
"createdAt": "2026-11-02T10:00:01.000Z"
}
]
},
"success": true,
"statusCode": 200,
"errorMessage": null
}