---
title: "List agent runs"
method: GET
path: "/api/agent-runs"
tags: ["Agent Runs"]
---

# List agent runs

`GET /api/agent-runs`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/agent-runs`
- Auth: HTTP bearer

Retrieve a paginated list of historical agent execution runs with optional filters.

## Query parameters

- `page` number: Page number for pagination (0-based, default: 0)
- `pageSize` number: Number of runs per page (1-100, default: 50)
- `sortField` 'createdAt' | 'updatedAt' | 'agentName' | 'modelAlias' | 'evalScore' | 'durationMs': Field to sort by (default: createdAt)
- `sortDirection` 'asc' | 'desc': Sort direction (default: desc)
- `agentIdFilter` string, uuid: Optional filter by exact agent id
- `agentNameFilter` string: Optional filter by agent name (partial match)
- `searchQuery` string: Optional search across execution ID, run/alert title, and agent name (partial match)
- `toolFilter` string: Optional comma-separated list of tool names to filter by
- `dateFrom` string: Optional start date filter (ISO string)
- `dateTo` string: Optional end date filter (ISO string)
- `triggerSourceFilter` string: Optional comma-separated list of trigger source values (manual, jira, slack, etc.)
- `scoreFilters` string: Optional JSON array of { op: gt|lt|eq|ge|le, value: number } for eval score filtering (applied as OR)
- `noteworthyFilter` string: When true, only return noteworthy runs: those with critical issues, failed acceptance criteria, or high/critical severity detection hits
- `needsAttentionFilter` string: When true, only return runs with critical issues or failed acceptance criteria
- `includeTotalCount` string: When false, skip the exact pagination count and return zero for totalCount

## Response `200`

Successful response

- object: Paginated list of agent execution runs with filtering and sorting
  - `runs` object[], required: Array of agent run summaries matching the query
    - `id` string, uuid, required: Unique identifier for the agent run
    - `agentId` string, uuid, required: ID of the agent that performed this run
    - `agentName` string, required: Name of the agent that performed this run
    - `agentType` 'response' | 'detection', required: Type of agent: response (standard agent) or detection (security detection agent)
    - `runTitle` string, required: Title/description of the run
    - `createdAt` string, required: ISO timestamp when the run was created
    - `updatedAt` string, required: ISO timestamp when the run was last updated
    - `modelAlias` string, required: Alias of the model used for this run
    - `modelName` string: Full name of the model used for this run
    - `toolNames` string[], required: Names of tools used in this run (limited to first 5 tools for display)
    - `totalToolCount` integer, required: Total number of tools invoked during this run
    - `triggerSource` string, nullable: Source that triggered the run (e.g., manual, api, jira, slack, linear, cron, webhook, email)
    - `triggerName` string, nullable: Name of the specific trigger that initiated the run
    - `hasError` boolean, required: Whether the run encountered any errors
    - `isStreaming` boolean, required: Whether the run is currently streaming (in-progress)
    - `status` 'queued' | 'running' | 'waiting' | 'done' | 'error' | 'interrupted': Chat execution status: queued (created but not yet claimed), running (actively executing), waiting (awaiting user response), done (completed), error (failed), interrupted (stopped by user)
    - `evalScore` number, nullable: LLM evaluation score for this run (0-10 scale, null if not evaluated)
    - `evalExplanation` string, nullable: Explanation of the evaluation score
    - `evalBulletSummary` string[], nullable: Bullet-point summary of evaluation findings
    - `criticalIssue` object, nullable: Critical external blocker detected by LLM judge evaluation
      - `category` 'authentication' | 'connectivity' | 'missing_data' | 'permission' | 'configuration' | 'service_unavailable' | 'content_filter', required: Category of the critical issue (see: authentication, connectivity, missing_data, permission, configuration, service_unavailable)
      - `explanation` string, required: One sentence explaining what went wrong
    - `acceptanceCriteriaResults` object[], nullable: Acceptance criteria evaluation results for this run
      - `criterion` string, required: The acceptance criterion being evaluated
      - `met` boolean, required: Whether the agent run satisfied this acceptance criterion
      - `explanation` string, required: Brief explanation of why the criterion was or was not met
    - `linkedAlert` object, nullable: Alert this run created or triaged, when available to the caller
      - `displayId` string, required: Human-readable alert identifier
      - `title` string, required: Linked alert title
      - `status` 'open' | 'in_progress' | 'escalated' | 'closed_true_positive' | 'closed_false_positive' | 'closed_true_positive_benign' | 'dismissed' | 'duplicate' | 'expired', required: Current linked alert status
    - `parentRun` object, nullable: Parent agent run that delegated this execution, when readable by the caller
      - `id` string, uuid, required: ID of the parent agent run that delegated this execution
      - `agentId` string, uuid, required: ID of the agent that delegated this execution
      - `agentName` string, required: Name of the agent that delegated this execution
      - `agentType` 'response' | 'detection', required: Type of the agent that delegated this execution
      - `runTitle` string, required: Title of the parent agent run
    - `deliveries` object[]: Output deliveries and notifications issued for this run, oldest first
      - `id` string, uuid, required: Delivery ID
      - `purpose` 'response' | 'acceptance-criteria', required: What was sent
      - `destinationId` string, uuid, required: Output destination ID
      - `destinationType` 'webhook' | 'teams' | 'slack' | 'pagerduty' | 'linear' | 'tines' | 'incidentio', required: Destination type
      - `destinationName` string, required: Destination name
      - `status` 'pending' | 'in_progress' | 'retrying' | 'sent' | 'failed', required: Status of the current attempt
      - `partial` boolean, required: True when the send succeeded but at least one target (e.g. a Slack channel) was skipped
      - `updatedAt` string, required: ISO timestamp of the last status change
    - `durationMs` number, nullable: How long the run took in milliseconds, summed over its turns; null while it is working or waiting, or when unknown
  - `totalCount` integer, required: Total number of runs matching the filters (for pagination)

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `500`: Internal server error

---

[API](https://skmtc.dev/cotool/apis/cotool-api.md) - [All operations](https://skmtc.dev/cotool/apis/cotool-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cotool/apis/cotool-api/revisions/f5abe0add203?raw)