> ## 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 detection runs > Retrieve runs for a specific detection. Supports server-side pagination via `limit`/`offset` and a `filter` query parameter (`all`, `hits`, `clear`, `errors`) that mirrors the agent list view's definition of a hit (rows present in the `detection_hits` table). ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json get /api/detections/{id}/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/detections/{id}/runs: get: tags: - Detections summary: List detection runs description: >- Retrieve runs for a specific detection. Supports server-side pagination via `limit`/`offset` and a `filter` query parameter (`all`, `hits`, `clear`, `errors`) that mirrors the agent list view's definition of a hit (rows present in the `detection_hits` table). parameters: - in: path name: id description: Detection UUID schema: type: string format: uuid description: Detection UUID required: true - in: query name: limit description: Page size, defaults to 25. schema: type: integer minimum: 1 maximum: 100 description: Page size, defaults to 25. - in: query name: offset description: Offset into the result set, defaults to 0. schema: type: integer minimum: 0 description: Offset into the result set, defaults to 0. - in: query name: filter description: Optional server-side filter on run kind. Defaults to "all". schema: type: string enum: - all - hits - clear - errors description: Optional server-side filter on run kind. Defaults to "all". 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 run identifier title: type: string description: Title of the run detectionId: type: string format: uuid description: ID of the detection that was run organizationId: type: string format: uuid description: Organization that owns this run createdAt: type: string description: ISO timestamp when run was created updatedAt: type: string description: ISO timestamp when run was last updated isStreaming: type: boolean description: Whether the run is currently streaming hasError: type: boolean description: Whether the run encountered an error result: type: - object - 'null' properties: detectionTriggered: type: boolean description: Whether the detection was triggered confidence: type: number minimum: 0 maximum: 100 description: Confidence score (0-100) individualEntities: type: array items: type: object properties: entityType: type: string description: Type of entity confidence: type: number description: Confidence for this entity evidence: type: array items: type: string description: Evidence strings summary: type: string description: >- A one sentence summary detailing whether this entity is triggered and the rationale either way headline: type: string cta: type: string description: >- If relevant, a call to action for the security engineer responding to this triggered alert. What should they do? Only relevant for triggered entities statistics: type: array items: type: string description: >- Statistics for this entity which are relevant to the detection severity: type: string enum: - low - medium - high - critical description: >- The severity of the entity. Should be one of the following: "low", "medium", "high", "critical". If this entity is a true positive, what is the impact to the end organization? entity: type: string description: The entity examined triggered: type: boolean description: Whether this entity triggered hitId: type: string format: uuid description: >- UUID of the recorded detection hit for this entity, when one was persisted. Required to resolve verifierEvidence citations via the cited-tool-calls endpoint. Omitted for clear (untriggered) entities. verifierEvidence: type: array items: type: string description: >- Curated evidence bullets authored by the hit-verification sub-agent. Each bullet may contain inline ... spans pointing at the tool calls that established it. Frontend should prefer these over the parent agent's plain `evidence` array when present. description: Per-entity results description: The detection result entityCount: type: number description: Total number of entities examined triggeredEntityCount: type: number description: Number of entities that triggered recordedHitCount: type: integer minimum: 0 description: >- Number of persisted detection hits for this run (canonical "did this trigger?" signal) recordedHitSamples: type: array items: type: object properties: entity: type: string entityType: type: - string - 'null' severity: type: string enum: - low - medium - high - critical summary: type: - string - 'null' headline: type: - string - 'null' required: - entity - entityType - severity - summary - headline description: >- Representative hit rows for this run; up to 4 entries. evalScore: type: - number - 'null' description: Evaluation score if available evalExplanation: type: - string - 'null' description: Evaluation explanation if available evalBulletSummary: type: - array - 'null' items: type: string description: Bullet point summary of evaluation required: - id - title - detectionId - organizationId - createdAt - updatedAt - isStreaming - hasError - result - entityCount - triggeredEntityCount description: Array of detection runs totalCount: type: number description: Total number of runs required: - runs - totalCount '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/detections/:id/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` ````