Skip to main content
GET
/
api
/
agents
/
{agentId}
/
runs
List Agent Runs
curl --request GET \
  --url https://api.example.com/api/agents/{agentId}/runs
{
  "runs": [
    {
      "runId": "550e8400-e29b-41d4-a716-446655440001",
      "status": "completed",
      "startedAt": 1703001234567,
      "endedAt": 1703001235890,
      "durationMs": 1323,
      "messageId": "770e8400-e29b-41d4-a716-446655440003",
      "roomId": "660e8400-e29b-41d4-a716-446655440002",
      "entityId": "880e8400-e29b-41d4-a716-446655440004",
      "counts": {
        "actions": 2,
        "modelCalls": 3,
        "errors": 0,
        "evaluators": 1
      }
    }
  ],
  "total": 42,
  "hasMore": true
}
List all execution runs for a specific agent. Runs track the lifecycle of message processing including actions executed, evaluators run, and timing data.

​
Path Parameters

​
agentId
string
required
The UUID of the agent

​
Query Parameters

​
status
string
Filter by run status: started, completed, timeout, error, or all
​
roomId
string
Filter runs by room ID
​
limit
number
default:"20"
Maximum number of runs to return (max: 100)
​
from
number
Return only runs started after this Unix timestamp
​
to
number
Return only runs started before this Unix timestamp

​
Headers

​
X-Entity-Id
string
Optional entity ID for Row-Level Security (RLS) filtering

​
Response

​
runs
array
Array of run summaries
​
total
number
Total number of runs matching the filter
​
hasMore
boolean
Whether there are more runs available
{
  "runs": [
    {
      "runId": "550e8400-e29b-41d4-a716-446655440001",
      "status": "completed",
      "startedAt": 1703001234567,
      "endedAt": 1703001235890,
      "durationMs": 1323,
      "messageId": "770e8400-e29b-41d4-a716-446655440003",
      "roomId": "660e8400-e29b-41d4-a716-446655440002",
      "entityId": "880e8400-e29b-41d4-a716-446655440004",
      "counts": {
        "actions": 2,
        "modelCalls": 3,
        "errors": 0,
        "evaluators": 1
      }
    }
  ],
  "total": 42,
  "hasMore": true
}