---
title: "List alerts"
method: GET
path: "/api/alerts"
tags: ["Alerts"]
---

# List alerts

`GET /api/alerts`

## Request

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

Retrieve first-class alert work items for the current organization. Archived dismissed, duplicate, and expired alerts are excluded unless a status filter is provided.

## Query parameters

- `limit` integer: Maximum number of alerts to return per page
- `offset` integer: Number of alerts to skip for pagination
- `status` string: Comma-separated alert statuses to include
- `source` string: Comma-separated alert source names to include
- `severity` string: Comma-separated severities to include
- `assignedAgentId` string, uuid: Only include alerts assigned to this response agent
- `detection` string: Alert detection filter key returned by /api/alerts/filter-options
- `detectionId` string, uuid: Only include alerts tied to this Cotool detection
- `originAgentId` string, uuid: Only include alerts created by this origin agent
- `originDetectionHitId` string, uuid: Only include the alert created from this detection hit
- `createdAfter` string, date-time: Only include alerts created at or after this ISO timestamp
- `createdBefore` string, date-time: Only include alerts created before this ISO timestamp
- `q` string: Free-text search over alert title, description, detection name, and origin references
- `sort` 'created' | 'severity': Sort order. "created" (default) is newest first. "severity" is critical before high before medium before low before unrated, then newest first, applied across all matching rows before pagination.

## Response `200`

Successful response

- object
  - `alerts` object[], required
    - `id` string, uuid, required: Internal alert identifier
    - `displayId` string, required: Human-readable alert identifier
    - `organizationId` string, uuid, required: Organization that owns the alert
    - `organizationName` string, required: URL-safe organization name used in durable alert paths
    - `title` string, required: Human-readable alert title
    - `description` string, nullable, required: Markdown summary or details for the alert
    - `severity` 'low' | 'medium' | 'high' | 'critical' | 'null', nullable, required: Alert severity when known
    - `status` 'open' | 'in_progress' | 'escalated' | 'closed_true_positive' | 'closed_false_positive' | 'closed_true_positive_benign' | 'dismissed' | 'duplicate' | 'expired', required: Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists.
    - `duplicateOfAlertId` string, uuid, nullable: Canonical alert this alert duplicates, when status is duplicate
    - `duplicateCount` integer, required: Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring.
    - `source` object, required: Filter-oriented source attribution for an alert.
      - `category` 'detection' | 'trigger' | 'hunt' | 'api' | 'agent', required: Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent.
      - `name` 'cotool_detection' | 'cotool_code' | 'cotool_signal' | 'hunt' | 'hunt_v2' | 'api' | 'agent' | 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon', required: Filter-oriented alert source name. Trigger-created alerts use the trigger type.
      - `triggerType` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: Trigger source when category is trigger
    - `detection` object, nullable, required: Detection attribution for the alert, when known.
      - `id` string, uuid, nullable, required: Cotool detection identifier when known
      - `agentId` string, uuid, nullable, required: Cotool detection agent identifier when known
      - `codeDetectionId` string, uuid, nullable: Code detection identifier when this alert came from Code Mode
      - `ruleId` string, uuid, nullable, required: Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule
      - `name` string, required: Detection display name
      - `kind` 'cotool' | 'cotool_code' | 'cotool_signal' | 'external', required: Whether this detection attribution is internal or extracted. `cotool_signal` alerts were promoted from a signal; their name is the signal type, and `codeDetectionId` is the streaming detection that emitted it.
      - `origin` 'user' | 'orchestrator' | 'null', nullable: Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature.
    - `createdBy` 'agent' | 'trigger' | 'system', required: Actor class that created the alert.
    - `originAgentId` string, uuid, nullable, required: Agent that produced or owns the source flow
    - `originTriggerId` string, uuid, nullable, required: Trigger that created this alert, when source is an external trigger
    - `originRunId` string, uuid, nullable, required: Run that minted the alert, stored as chats.id
    - `originDetectionHitId` string, uuid, nullable, required: Detection hit that produced this alert, when applicable
    - `codeDetectionId` string, uuid, nullable, required: Code detection that produced this alert, when applicable
    - `originCodeDetectionHitId` string, uuid, nullable, required: Code-detection hit that produced this alert, when applicable
    - `externalProvider` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: External trigger provider such as jira, linear, email, or webhook
    - `externalRef` string, nullable, required: Provider-native event, ticket, message, or alert identifier
    - `externalUrl` string, uri, nullable, required: Provider-native URL for the originating object
    - `assignedAgentId` string, uuid, nullable, required: Response agent currently assigned to triage this alert
    - `triageRunId` string, uuid, nullable, required: Latest response-agent triage run for this alert, stored as chats.id
    - `dedupeKey` string, nullable, required: Stable key used for idempotent alert creation
    - `createdAt` string, required: ISO timestamp when the alert was created
    - `updatedAt` string, required: ISO timestamp when the alert was last updated
    - `firstTriagedAt` string, nullable, required: ISO timestamp when triage first started
    - `resolvedAt` string, nullable, required: ISO timestamp when the alert reached a terminal closed status
    - `derivedDisposition` 'true_positive' | 'false_positive' | 'true_positive_benign' | 'null', nullable, required: Disposition derived from terminal alert status
    - `originAgentName` string, nullable, required: Display name for the origin agent, when available
    - `assignedAgentName` string, nullable, required: Display name for the assigned triage agent, when available
    - `triggerSource` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: Trigger source for external-trigger alerts
    - `resolvedByType` 'human' | 'agent' | 'system' | 'null', nullable: Actor class that moved the alert to its terminal status. Null while the alert is not closed.
    - `resolvedByUserId` string, uuid, nullable: User who closed the alert, when a human closed it
    - `resolvedByAgentName` string, nullable: Display name of the agent that closed the alert, when an agent closed it
    - `resolvedReason` string, nullable: Reason recorded with the closing status change, when provided
    - `huntQualifiedBy` 'compromise_signal_found' | 'exposure_found' | 'null', nullable: Qualifying condition that opened this Hunt alert. Null for non-hunt alerts.
    - `alternativeExplanationCount` integer: Number of alternative explanations offered on the latest escalation. Only meaningful while the alert is escalated.
  - `totalCount` integer, required: Total number of matching alerts 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)