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
}