> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elizaos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agent Runs

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

<ParamField path="agentId" type="string" required>
  The UUID of the agent
</ParamField>

## Query Parameters

<ParamField query="status" type="string">
  Filter by run status: `started`, `completed`, `timeout`, `error`, or `all`
</ParamField>

<ParamField query="roomId" type="string">
  Filter runs by room ID
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of runs to return (max: 100)
</ParamField>

<ParamField query="from" type="number">
  Return only runs started after this Unix timestamp
</ParamField>

<ParamField query="to" type="number">
  Return only runs started before this Unix timestamp
</ParamField>

## Headers

<ParamField header="X-Entity-Id" type="string">
  Optional entity ID for Row-Level Security (RLS) filtering
</ParamField>

## Response

<ResponseField name="runs" type="array">
  Array of run summaries

  <Expandable title="Run object">
    <ResponseField name="runId" type="string">
      Unique run identifier
    </ResponseField>

    <ResponseField name="status" type="string">
      Run status: `started`, `completed`, `timeout`, `error`
    </ResponseField>

    <ResponseField name="startedAt" type="number">
      Unix timestamp when run started
    </ResponseField>

    <ResponseField name="endedAt" type="number">
      Unix timestamp when run ended (null if still running)
    </ResponseField>

    <ResponseField name="durationMs" type="number">
      Duration in milliseconds (null if still running)
    </ResponseField>

    <ResponseField name="messageId" type="string">
      ID of the message that triggered this run
    </ResponseField>

    <ResponseField name="roomId" type="string">
      Room where the run occurred
    </ResponseField>

    <ResponseField name="entityId" type="string">
      Entity that triggered the run
    </ResponseField>

    <ResponseField name="counts" type="object">
      Aggregated counts for the run

      <Expandable title="Counts object">
        <ResponseField name="actions" type="number">
          Number of actions executed
        </ResponseField>

        <ResponseField name="modelCalls" type="number">
          Number of model API calls made
        </ResponseField>

        <ResponseField name="errors" type="number">
          Number of errors encountered
        </ResponseField>

        <ResponseField name="evaluators" type="number">
          Number of evaluators run
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Total number of runs matching the filter
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether there are more runs available
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "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
  }
  ```
</ResponseExample>