Skip to main content
GET
/
api
/
agent-runs
cURL
curl -X GET "https://app.cotool.ai/api/agent-runs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
{
  "runs": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "agentName": "<string>",
      "agentType": "response",
      "runTitle": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "modelAlias": "<string>",
      "toolNames": [
        "<string>"
      ],
      "totalToolCount": 123,
      "hasError": true,
      "isStreaming": true,
      "modelName": "<string>",
      "triggerSource": "<string>",
      "triggerName": "<string>",
      "status": "running",
      "evalScore": 123,
      "evalExplanation": "<string>",
      "evalBulletSummary": [
        "<string>"
      ],
      "criticalIssue": {
        "category": "authentication",
        "explanation": "<string>"
      },
      "acceptanceCriteriaResults": [
        {
          "criterion": "<string>",
          "met": true,
          "explanation": "<string>"
        }
      ]
    }
  ],
  "totalCount": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

API Key authentication for programmatic access. Include your API key in the Authorization header as: Bearer your_api_key_here

Query Parameters

​
page
number
default:0

Page number for pagination (0-based, default: 0)

Required range: x >= 0
​
pageSize
number
default:50

Number of runs per page (1-100, default: 50)

Required range: 1 <= x <= 100
​
sortField
enum<string>
default:createdAt

Field to sort by (default: createdAt)

Available options:
createdAt,
updatedAt,
agentName,
modelAlias,
evalScore
​
sortDirection
enum<string>
default:desc

Sort direction (default: desc)

Available options:
asc,
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

Response

200 - application/json

Successful response

Paginated list of agent execution runs with filtering and sorting

​
runs
object[]
required

Array of agent run summaries matching the query

​
totalCount
integer
required

Total number of runs matching the filters (for pagination)