> ## 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 hits > Retrieve a flattened hit feed across all detections in the current organization. Pass `detectionId` to restrict the feed (and its aggregate summary) to a single detection — used by the detection-agent detail page to surface verifier evidence + cited tool calls without leaving the page. Uses a single batch query instead of N concurrent queries per detection. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json get /api/detections/hits 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/hits: get: tags: - Detections summary: List detection hits description: >- Retrieve a flattened hit feed across all detections in the current organization. Pass `detectionId` to restrict the feed (and its aggregate summary) to a single detection — used by the detection-agent detail page to surface verifier evidence + cited tool calls without leaving the page. Uses a single batch query instead of N concurrent queries per detection. parameters: - in: query name: limit description: 'Maximum number of hits to return per page (1-200, default: 100)' schema: type: integer minimum: 1 maximum: 200 default: 100 description: 'Maximum number of hits to return per page (1-200, default: 100)' - in: query name: offset description: 'Number of hits to skip for pagination (default: 0)' schema: type: integer minimum: 0 default: 0 description: 'Number of hits to skip for pagination (default: 0)' - in: query name: detectionId description: >- Restrict the feed to hits produced by a single detection agent. When omitted, returns hits across all accessible detections. schema: type: string format: uuid description: >- Restrict the feed to hits produced by a single detection agent. When omitted, returns hits across all accessible detections. - in: query name: severityFilter description: >- Comma-separated severities to include, such as "high,critical". When omitted, returns all severities. schema: type: string description: >- Comma-separated severities to include, such as "high,critical". When omitted, returns all severities. responses: '200': description: Successful response content: application/json: schema: type: object properties: hits: type: array items: type: object properties: id: type: string detectionId: type: string format: uuid detectionName: type: string detectionDescription: type: - string - 'null' detectionCategory: type: - string - 'null' detectionIsBuiltIn: type: boolean detectionSiemType: type: - string - 'null' runId: type: string format: uuid runTitle: type: string runCreatedAt: type: string hitCreatedAt: type: string description: When this hit was recorded isAutonomousHuntHit: type: boolean description: >- Whether this hit was recorded by the autonomous hunt orchestrator status: type: string enum: - open - dismissed_fp - dismissed_tpb - resolved_tp - dismissed_old statusHistory: type: array items: type: object properties: status: type: string enum: - open - dismissed_fp - dismissed_tpb - resolved_tp - dismissed_old description: Status after this transition at: type: string format: date-time description: >- ISO timestamp when the status transition occurred by: type: - string - 'null' format: uuid description: >- User who made the transition, or null for system-created entries reason: type: string description: Optional reason or note for the transition required: - status - at - by entityType: type: - string - 'null' confidence: type: - number - 'null' evidence: type: array items: type: string summary: type: - string - 'null' headline: type: - string - 'null' cta: type: - string - 'null' statistics: type: array items: type: string severity: type: string enum: - low - medium - high - critical entity: type: string 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. Omitted (or empty) when the verifier did not produce one. required: - id - detectionId - detectionName - detectionDescription - detectionCategory - detectionIsBuiltIn - detectionSiemType - runId - runTitle - runCreatedAt - hitCreatedAt - isAutonomousHuntHit - entityType - confidence - evidence - summary - headline - cta - statistics - severity - entity totalCount: type: number description: >- Total number of hits across all detections (for pagination) summary: type: object properties: uniqueDetections: type: integer minimum: 0 description: >- Number of distinct detections represented by all matching hits avgConfidence: type: number minimum: 0 description: >- Average confidence across all matching hits with a numeric confidence value hitsLast24h: type: integer minimum: 0 description: Number of matching hits created in the last 24 hours hitsOverTime: type: array items: type: object properties: date: type: string description: UTC date key in YYYY-MM-DD format count: type: integer minimum: 0 required: - date - count description: Daily hit counts for the trailing 30 days (UTC) severityCounts: type: object properties: critical: type: integer minimum: 0 high: type: integer minimum: 0 medium: type: integer minimum: 0 low: type: integer minimum: 0 required: - critical - high - medium - low description: Severity distribution across all matching hits required: - uniqueDetections - avgConfidence - hitsLast24h - hitsOverTime - severityCounts description: >- Aggregate summary for all matching hits (returned on initial page load) required: - hits - 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/hits" \ -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` ````