> ## 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. # List agent runs > Retrieve a paginated list of historical agent execution runs with optional filters. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json get /api/agent-runs openapi: 3.1.0 info: title: Cotool API version: 1.0.0 description: >- # Cotool API Documentation The Cotool API allows you to interact with the Cotool platform programmatically, enabling you to build powerful integrations and automate your workflows. ## Getting an API Key Follow these steps to generate your API key: 1. **Log in** to the Cotool web interface 2. **Navigate** to `/settings/api-keys` 3. **Click** "Generate Key" 4. **Copy and store** your API key securely ⚠️ *It won't be shown again* ## API Key Authentication For programmatic access and integrations, use your API key with the Authorization header: ```http Authorization: Bearer your_api_key_here ``` ```bash curl -X GET "https://app.cotool.ai/api/endpoint" \ -H "Authorization: Bearer your_api_key_here" \ -H "Content-Type: application/json" ``` servers: - url: https://app.cotool.ai description: Production server security: - ApiKeyAuth: [] paths: /api/agent-runs: get: tags: - Agents summary: List agent runs description: >- Retrieve a paginated list of historical agent execution runs with optional filters. parameters: - in: query name: page description: 'Page number for pagination (0-based, default: 0)' schema: type: number minimum: 0 default: 0 description: 'Page number for pagination (0-based, default: 0)' - in: query name: pageSize description: 'Number of runs per page (1-100, default: 50)' schema: type: number minimum: 1 maximum: 100 default: 50 description: 'Number of runs per page (1-100, default: 50)' - in: query name: sortField description: 'Field to sort by (default: createdAt)' schema: type: string enum: - createdAt - updatedAt - agentName - modelAlias - evalScore default: createdAt description: 'Field to sort by (default: createdAt)' - in: query name: sortDirection description: 'Sort direction (default: desc)' schema: type: string enum: - asc - desc default: desc description: 'Sort direction (default: desc)' - in: query name: agentIdFilter description: Optional filter by exact agent id schema: type: string format: uuid description: Optional filter by exact agent id - in: query name: agentNameFilter description: Optional filter by agent name (partial match) schema: type: string description: Optional filter by agent name (partial match) - in: query name: searchQuery description: >- Optional search across execution ID, run/alert title, and agent name (partial match) schema: type: string description: >- Optional search across execution ID, run/alert title, and agent name (partial match) - in: query name: toolFilter description: Optional comma-separated list of tool names to filter by schema: type: string description: Optional comma-separated list of tool names to filter by - in: query name: dateFrom description: Optional start date filter (ISO string) schema: type: string description: Optional start date filter (ISO string) - in: query name: dateTo description: Optional end date filter (ISO string) schema: type: string description: Optional end date filter (ISO string) - in: query name: triggerSourceFilter description: >- Optional comma-separated list of trigger source values (manual, jira, slack, etc.) schema: type: string description: >- Optional comma-separated list of trigger source values (manual, jira, slack, etc.) - in: query name: scoreFilters description: >- Optional JSON array of { op: gt|lt|eq|ge|le, value: number } for eval score filtering (applied as OR) schema: type: string description: >- Optional JSON array of { op: gt|lt|eq|ge|le, value: number } for eval score filtering (applied as OR) - in: query name: noteworthyFilter description: >- When true, only return noteworthy runs: those with critical issues, failed acceptance criteria, or high/critical severity detection hits schema: type: string description: >- When true, only return noteworthy runs: those with critical issues, failed acceptance criteria, or high/critical severity detection hits - in: query name: needsAttentionFilter description: >- When true, only return runs with critical issues or failed acceptance criteria schema: type: string description: >- When true, only return runs with critical issues or failed acceptance criteria responses: '200': description: Successful response content: application/json: schema: type: object properties: runs: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier for the agent run agentId: type: string format: uuid description: ID of the agent that performed this run agentName: type: string description: Name of the agent that performed this run agentType: type: string enum: - response - detection description: >- Type of agent: response (standard agent) or detection (security detection agent) runTitle: type: string description: Title/description of the run createdAt: type: string description: ISO timestamp when the run was created updatedAt: type: string description: ISO timestamp when the run was last updated modelAlias: type: string description: Alias of the model used for this run modelName: type: string description: Full name of the model used for this run toolNames: type: array items: type: string description: >- Names of tools used in this run (limited to first 5 tools for display) totalToolCount: type: integer description: Total number of tools invoked during this run triggerSource: type: - string - 'null' description: >- Source that triggered the run (e.g., manual, api, jira, slack, linear, cron, webhook, email) triggerName: type: - string - 'null' description: Name of the specific trigger that initiated the run hasError: type: boolean description: Whether the run encountered any errors isStreaming: type: boolean description: Whether the run is currently streaming (in-progress) status: type: string enum: - queued - running - waiting - done - error - interrupted description: >- 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: type: - number - 'null' description: >- LLM evaluation score for this run (0-10 scale, null if not evaluated) evalExplanation: type: - string - 'null' description: Explanation of the evaluation score evalBulletSummary: type: - array - 'null' items: type: string description: Bullet-point summary of evaluation findings criticalIssue: type: - object - 'null' properties: category: type: string enum: - authentication - connectivity - missing_data - permission - configuration - service_unavailable description: >- Category of the critical issue (see: authentication, connectivity, missing_data, permission, configuration, service_unavailable) explanation: type: string description: One sentence explaining what went wrong required: - category - explanation description: >- Critical external blocker detected by LLM judge evaluation acceptanceCriteriaResults: type: - array - 'null' items: type: object properties: criterion: type: string description: The acceptance criterion being evaluated met: type: boolean description: >- Whether the agent run satisfied this acceptance criterion explanation: type: string description: >- Brief explanation of why the criterion was or was not met required: - criterion - met - explanation description: Acceptance criteria evaluation results for this run linkedAlert: type: - object - 'null' properties: displayId: type: string description: Human-readable alert identifier title: type: string description: Linked alert title status: type: string enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign description: Current linked alert status required: - displayId - title - status description: >- Alert this run created or triaged, when available to the caller required: - id - agentId - agentName - agentType - runTitle - createdAt - updatedAt - modelAlias - toolNames - totalToolCount - hasError - isStreaming description: Array of agent run summaries matching the query totalCount: type: integer description: Total number of runs matching the filters (for pagination) required: - runs - totalCount description: >- Paginated list of agent execution runs with filtering and sorting '400': description: Bad request — input validation failed or the request was malformed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized — missing or invalid API key / session content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — the authenticated user lacks the required permissions content: application/json: schema: $ref: '#/components/schemas/PermissionError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: |- curl -X GET "https://app.cotool.ai/api/agent-runs" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" components: schemas: ValidationError: type: object properties: error: type: string description: Error message describing what went wrong issues: type: array description: >- Detailed validation issues, present when request or response schema validation fails items: type: object additionalProperties: true required: - error Error: type: object properties: error: type: string description: Error message describing what went wrong required: - error PermissionError: type: object properties: error: type: string description: Error message describing what went wrong missingPerms: type: array description: Permissions the authenticated user is missing for this operation items: type: string required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key authentication for programmatic access. Include your API key in the Authorization header as: `Bearer your_api_key_here` ````