> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threataware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Alerts

> Request a list of all alerts throughout your entire environment

## Overview

The Alerts endpoint provides access to security issues and Vitals health problems detected across your environment. Filter by resolution status or specific integration.

## Parameters

<ParamField query="filter" type="string" required>
  Filter alerts based on their current state

  **Options:**

  * `allunresolved` - All unresolved alerts
  * `all` - All alerts (resolved and unresolved)
  * `resolved` - Only resolved alerts
</ParamField>

<ParamField query="systemName" type="string">
  Name of an integration you would like to query against. Leave blank to query all integrations.

  Example: `automox`, `crowdstrike`, `msdefenderatp`
</ParamField>

<ParamField query="offset" type="number" default="0">
  Set the start position of the data returned by the API
</ParamField>

<ParamField query="limit" type="number" default="0">
  Limit each request by the provided number. Leave blank or as 0 to return all data available
</ParamField>

## Authentication

<ParamField header="X-ThreatAware-ApiKey" type="string" required>
  Your ThreatAware API key
</ParamField>

<ParamField header="Accept" type="string" default="application/json">
  Response format
</ParamField>

## Response

<ResponseField name="offset" type="number">
  The starting position of this result set
</ResponseField>

<ResponseField name="limit" type="number">
  The number of results returned
</ResponseField>

<ResponseField name="total" type="number">
  Total number of alerts available
</ResponseField>

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="statusCode" type="number">
  HTTP status code
</ResponseField>

<ResponseField name="message" type="string">
  Status message
</ResponseField>

<ResponseField name="data" type="array">
  <Expandable title="Alert Object">
    <ResponseField name="state" type="string">
      Alert severity: `Red`, `Amber`, `Green`
    </ResponseField>

    <ResponseField name="product" type="string">
      Integration and category (e.g., "Automox, Software Updates")
    </ResponseField>

    <ResponseField name="status" type="string">
      Alert type: `Incident`, `Warning`, `Info`
    </ResponseField>

    <ResponseField name="item" type="string">
      Device or user name affected by this alert
    </ResponseField>

    <ResponseField name="issue" type="string">
      Brief description of the issue
    </ResponseField>

    <ResponseField name="details" type="string">
      Detailed information about the alert
    </ResponseField>

    <ResponseField name="itemEntityType" type="string">
      Type of entity: `device`, `user`, `system`
    </ResponseField>

    <ResponseField name="ownerName" type="string">
      User assigned to this alert
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      When the alert was created (ISO 8601)
    </ResponseField>

    <ResponseField name="acknowledgedTime" type="string">
      When the alert was acknowledged
    </ResponseField>

    <ResponseField name="assignedTime" type="string">
      When the alert was assigned
    </ResponseField>

    <ResponseField name="resolved" type="boolean">
      Whether the alert has been resolved
    </ResponseField>

    <ResponseField name="acknowledged" type="boolean">
      Whether the alert has been acknowledged
    </ResponseField>

    <ResponseField name="resolvedBy" type="string">
      User who resolved the alert
    </ResponseField>

    <ResponseField name="resolvedTime" type="string">
      When the alert was resolved
    </ResponseField>

    <ResponseField name="itemId" type="string">
      Unique identifier for the affected item
    </ResponseField>

    <ResponseField name="inactiveUntil" type="string">
      Alert snooze expiration time
    </ResponseField>

    <ResponseField name="hasLinkedDevice" type="boolean">
      Whether this alert is linked to a device in inventory
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://your-cloud-id.threataware.com/public-api/v1/alerts?filter=allunresolved&limit=10' \
    --header 'Accept: application/json' \
    --header 'X-ThreatAware-ApiKey: your-api-key-here'
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "your-api-key-here"
  CLOUD_ID = "sandbox"
  BASE_URL = f"https://{CLOUD_ID}.threataware.com/public-api/v1"

  headers = {
      "Accept": "application/json",
      "X-ThreatAware-ApiKey": API_KEY
  }

  params = {
      "filter": "allunresolved",
      "limit": 10
  }

  response = requests.get(f"{BASE_URL}/alerts", headers=headers, params=params)
  alerts = response.json()

  print(f"Retrieved {len(alerts['data'])} unresolved alerts")

  # Example: Count by severity
  red_alerts = [a for a in alerts['data'] if a['state'] == 'Red']
  amber_alerts = [a for a in alerts['data'] if a['state'] == 'Amber']

  print(f"Red: {len(red_alerts)}, Amber: {len(amber_alerts)}")
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const API_KEY = 'your-api-key-here';
  const CLOUD_ID = 'sandbox';
  const BASE_URL = `https://${CLOUD_ID}.threataware.com/public-api/v1`;

  axios.get(`${BASE_URL}/alerts`, {
    headers: {
      'Accept': 'application/json',
      'X-ThreatAware-ApiKey': API_KEY
    },
    params: {
      filter: 'allunresolved',
      systemName: 'crowdstrike' // Optional: filter by integration
    }
  })
    .then(response => {
      console.log(`Retrieved ${response.data.data.length} CrowdStrike alerts`);
    });
  ```

  ```powershell PowerShell theme={null}
  $ApiKey = "your-api-key-here"
  $CloudId = "sandbox"
  $BaseUrl = "https://$CloudId.threataware.com/public-api/v1"

  $Headers = @{
      "Accept" = "application/json"
      "X-ThreatAware-ApiKey" = $ApiKey
  }

  $Params = @{
      filter = "allunresolved"
      limit = 10
  }

  $Response = Invoke-RestMethod -Uri "$BaseUrl/alerts" -Headers $Headers -Body $Params -Method Get

  Write-Host "Retrieved $($Response.data.Count) unresolved alerts"

  # Example: Group by state
  $Response.data | Group-Object -Property state | Format-Table Name, Count
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "offset": 0,
    "limit": 1,
    "total": 100,
    "data": [
      {
        "state": "Amber",
        "product": "Automox, Software Updates",
        "status": "Incident",
        "item": "LAPTOP-001-1IWEF",
        "issue": "Pending Updates",
        "details": "Pending update of 1 patch, overdue by 5 days: Security Update KB5012345",
        "itemEntityType": "device",
        "ownerName": "",
        "timestamp": "2022-10-10T09:32:23.0000000",
        "acknowledgedTime": "0001-01-01T00:00:00.0000000",
        "assignedTime": "0001-01-01T00:00:00.0000000",
        "resolved": false,
        "acknowledged": false,
        "resolvedBy": "",
        "resolvedTime": "0001-01-01T00:00:00.0000000",
        "itemId": "f4841fbf-412e-4504-82b8-ce3c8cd2d400",
        "inactiveUntil": "0001-01-01T00:00:00.0000000",
        "hasLinkedDevice": true
      }
    ],
    "success": true,
    "statusCode": 200,
    "message": "Successfully retrieved alerts."
  }
  ```
</ResponseExample>

## Use Cases

<CardGroup cols={2}>
  <Card title="SIEM Integration" icon="shield-halved">
    Forward security alerts to Splunk, Sentinel, QRadar, or other SIEMs
  </Card>

  <Card title="SOC Dashboard" icon="desktop">
    Build real-time security operations dashboards
  </Card>

  <Card title="Automated Ticketing" icon="ticket">
    Create ServiceNow or Jira tickets automatically from alerts
  </Card>

  <Card title="Alert Metrics" icon="chart-bar">
    Track Mean Time To Detect (MTTD) and Mean Time To Resolve (MTTR)
  </Card>
</CardGroup>

## Alert States

<AccordionGroup>
  <Accordion title="Red Alerts">
    **Critical security issues requiring immediate attention**

    Examples:

    * EDR agent not functioning
    * Encryption disabled on sensitive device
    * Critical vulnerability unpatched for 30+ days
    * MFA not enabled for admin account
  </Accordion>

  <Accordion title="Amber Alerts">
    **Warnings that should be addressed soon**

    Examples:

    * Agent configuration drift
    * Pending security updates
    * Device not seen online in 7-14 days
    * Firewall disabled temporarily
  </Accordion>

  <Accordion title="Green/Info">
    **Informational alerts or resolved issues**

    Examples:

    * Agent successfully installed
    * Configuration corrected
    * Device came back online
    * Patch successfully applied
  </Accordion>
</AccordionGroup>

## Related Endpoints

<Card title="Devices" icon="laptop" href="/api-reference/devices">
  Get full device details for affected items
</Card>