Alert Logs

Query and retrieve alert execution history to track when alerts were triggered and what notifications were sent.

---

Endpoint

GET /api/alertlogs

Retrieves a list of alert execution records with optional filtering, sorting, and pagination.

---

Authentication

Requires any valid API Key. All keys have read access.

---

Query Parameters

Parameter	Type	Default	Description
search	string	Empty	Query using alert log search syntax
skip	integer	0	Number of records to skip (for pagination)
take	integer	50	Number of records to return

---

Response

Returns a paginated list of alert log entries:

{
  "items": [
    {
      "id": "log-uuid",
      "alertId": "alert-uuid",
      "alertName": "High-Volume PII Detection",
      "notificationTypes": [0, 1],
      "emailRecipients": ["security@company.com"],
      "slackChannels": ["channel-uuid"],
      "activitySearchQuery": "detected in (true)",
      "occurrencesCount": 15,
      "timestamp": 1704067200,
      "isTest": false
    }
  ],
  "count": 42,
  "orderBy": [
    {
      "field": "timestamp",
      "order": "desc"
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Unique identifier for this log entry
alertId	string	ID of the alert that was triggered
alertName	string	Name of the alert
notificationTypes	integer[]	Notification types sent (0=email, 1=slack, 2=teams, 3=webhook)
emailRecipients	string[]	Email addresses that received notifications
slackChannels	string[]	Slack channel UUIDs that received notifications
activitySearchQuery	string	Activity search query that triggered the alert
occurrencesCount	integer	Number of activities that matched the alert conditions
timestamp	integer	Unix timestamp when the alert was triggered
isTest	boolean	Whether this was a test alert

---

Search Syntax

Use the search parameter to filter alert logs using the activity query language.

Available Fields

Field	Type	Description	Example
alert_name	string	Name of the alert	alert_name = "SecurityAlert"
timestamp	date	When alert was triggered	timestamp >= '-7d'
occurrences_count	integer	Match count	occurrences_count > 10
email_recipients	string[]	Email recipients	email_recipients contains ("admin@example.com")
slack_channels	string[]	Slack channels	slack_channels contains ("channel-uuid")
notification_types	integer[]	Notification types	notification_types contains (0)

Operators

Operator	Description	Example
=	Equals	alert_name = "PII Alert"
!=	Not equals	isTest != true
>, <, >=, <=	Comparison	occurrences_count >= 5
in (...)	Value in list	alert_name in ("Alert1", "Alert2")
contains (...)	Array contains values	email_recipients contains ("security@company.com")
and, or	Logical operators	timestamp >= '-7d' and occurrences_count > 10
order by	Sort results	order by timestamp desc

Time Formats

Format	Description
'-7d'	7 days ago
'-24h'	24 hours ago
'-1h'	1 hour ago
'2024-01-01T00:00:00Z'	Absolute timestamp (ISO 8601)

---

Building Queries with ConvertSearch

Instead of manually constructing query strings, you can use the ConvertSearch API to generate them programmatically. The same endpoint supports both activity and alert log queries.

Alert-Specific Fields

The ConvertSearch API supports these alert log fields:

Field	Type	Description	Example
alertNames	string[]	Alert name(s) to filter by	["High-Volume PII Detection"]
notificationTypes	string[]	Notification types sent	["email", "slack"]
slackChannels	string[]	Slack channel UUIDs	["channel-uuid"]
emailRecipients	string[]	Email addresses	["security@company.com"]

You can also use timestamp filters and combine them with alert-specific fields.

Example: Convert and Query

PythonNode.js

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Step 1: Convert filters to query string
convert_body = {
    "simpleToAdvanced": {
        "alertNames": ["High-Volume PII Detection"],
        "timestamp": {"withinLast": {"days": 7, "hours": 0, "minutes": 0}}
    }
}

convert_response = requests.post(
    f"{BASE_URL}/api/activities/convertsearch",
    headers=HEADERS,
    json=convert_body
)

query_string = convert_response.json()["simpleToAdvanced"]

# Step 2: Use query string with alertlogs endpoint
response = requests.get(
    f"{BASE_URL}/api/alertlogs",
    headers=HEADERS,
    params={"search": query_string}
)

for log in response.json()["items"]:
    print(f"{log['alertName']}: {log['occurrencesCount']} occurrences")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

// Step 1: Convert filters to query string
const convertBody = {
  simpleToAdvanced: {
    alertNames: ['High-Volume PII Detection'],
    timestamp: { withinLast: { days: 7, hours: 0, minutes: 0 } }
  }
};

const convertResponse = await axios.post(
  `${BASE_URL}/api/activities/convertsearch`,
  convertBody,
  { headers: HEADERS }
);

const queryString = convertResponse.data.simpleToAdvanced;

// Step 2: Use query string with alertlogs endpoint
const response = await axios.get(`${BASE_URL}/api/alertlogs`, {
  headers: HEADERS,
  params: { search: queryString }
});

response.data.items.forEach(log => {
  console.log(`${log.alertName}: ${log.occurrencesCount} occurrences`);
});

---

Examples

Recent Alert Logs

Retrieve alert logs from the last 7 days, sorted by most recent:

cURLPythonNode.js

curl -X GET "https://your-shield-host:8080/api/alertlogs?search=timestamp%20%3E%3D%20%27-7d%27%20order%20by%20timestamp%20desc&take=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

params = {
    "search": "timestamp >= '-7d' order by timestamp desc",
    "take": 25
}

response = requests.get(f"{BASE_URL}/api/alertlogs", headers=HEADERS, params=params)
logs = response.json()

for log in logs["items"]:
    print(f"{log['alertName']}: {log['occurrencesCount']} occurrences at {log['timestamp']}")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

const response = await axios.get(`${BASE_URL}/api/alertlogs`, {
  headers: HEADERS,
  params: {
    search: "timestamp >= '-7d' order by timestamp desc",
    take: 25
  }
});

response.data.items.forEach(log => {
  console.log(`${log.alertName}: ${log.occurrencesCount} occurrences at ${log.timestamp}`);
});

High-Volume Alerts

Find alerts triggered with more than 50 occurrences:

cURLPythonNode.js

curl -X GET "https://your-shield-host:8080/api/alertlogs?search=occurrences_count%20%3E%2050%20order%20by%20occurrences_count%20desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

params = {
    "search": "occurrences_count > 50 order by occurrences_count desc"
}

response = requests.get(f"{BASE_URL}/api/alertlogs", headers=HEADERS, params=params)

for log in response.json()["items"]:
    print(f"{log['alertName']}: {log['occurrencesCount']} occurrences")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

const response = await axios.get(`${BASE_URL}/api/alertlogs`, {
  headers: HEADERS,
  params: {
    search: 'occurrences_count > 50 order by occurrences_count desc'
  }
});

response.data.items.forEach(log => {
  console.log(`${log.alertName}: ${log.occurrencesCount} occurrences`);
});

Specific Alert History

View execution history for a specific alert:

cURLPythonNode.js

ALERT_NAME="High-Volume PII Detection"

curl -X GET "https://your-shield-host:8080/api/alertlogs?search=alert_name%20%3D%20%22${ALERT_NAME}%22%20order%20by%20timestamp%20desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

alert_name = "High-Volume PII Detection"

params = {
    "search": f'alert_name = "{alert_name}" order by timestamp desc'
}

response = requests.get(f"{BASE_URL}/api/alertlogs", headers=HEADERS, params=params)

print(f"Found {response.json()['count']} executions of '{alert_name}':")
for log in response.json()["items"]:
    print(f"  - {log['timestamp']}: {log['occurrencesCount']} occurrences")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

const alertName = 'High-Volume PII Detection';

const response = await axios.get(`${BASE_URL}/api/alertlogs`, {
  headers: HEADERS,
  params: {
    search: `alert_name = "${alertName}" order by timestamp desc`
  }
});

console.log(`Found ${response.data.count} executions of '${alertName}':`);
response.data.items.forEach(log => {
  console.log(`  - ${log.timestamp}: ${log.occurrencesCount} occurrences`);
});

Alerts by Notification Channel

Find alerts sent to specific email address:

PythonNode.js

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

email = "security@company.com"

params = {
    "search": f'email_recipients contains ("{email}") order by timestamp desc',
    "take": 50
}

response = requests.get(f"{BASE_URL}/api/alertlogs", headers=HEADERS, params=params)

print(f"Alerts sent to {email}:")
for log in response.json()["items"]:
    print(f"  - {log['alertName']}: {log['occurrencesCount']} occurrences")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

const email = 'security@company.com';

const response = await axios.get(`${BASE_URL}/api/alertlogs`, {
  headers: HEADERS,
  params: {
    search: `email_recipients contains ("${email}") order by timestamp desc`,
    take: 50
  }
});

console.log(`Alerts sent to ${email}:`);
response.data.items.forEach(log => {
  console.log(`  - ${log.alertName}: ${log.occurrencesCount} occurrences`);
});

Pagination

Retrieve large result sets with pagination:

PythonNode.js

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

page = 0
page_size = 100
all_logs = []

while True:
    params = {
        "search": "timestamp >= '-30d' order by timestamp desc",
        "skip": page * page_size,
        "take": page_size
    }

    response = requests.get(f"{BASE_URL}/api/alertlogs", headers=HEADERS, params=params)
    data = response.json()

    all_logs.extend(data["items"])

    # Break if we've retrieved all records
    if len(data["items"]) < page_size:
        break

    page += 1

print(f"Retrieved {len(all_logs)} total alert logs from last 30 days")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

let page = 0;
const pageSize = 100;
const allLogs = [];

while (true) {
  const response = await axios.get(`${BASE_URL}/api/alertlogs`, {
    headers: HEADERS,
    params: {
      search: 'timestamp >= \'-30d\' order by timestamp desc',
      skip: page * pageSize,
      take: pageSize
    }
  });

  allLogs.push(...response.data.items);

  // Break if we've retrieved all records
  if (response.data.items.length < pageSize) {
    break;
  }

  page++;
}

console.log(`Retrieved ${allLogs.length} total alert logs from last 30 days`);

---

Understanding Alert Logs

How Logs Are Created

Alert logs are automatically created when:

1. An alert's conditions are met
2. The threshold (time window + occurrence count) is exceeded
3. Notifications are sent to configured channels

Each log entry represents one alert execution.

Log Retention

Alert logs are stored in Elasticsearch with the index alert_log_v3. Retention depends on your Elasticsearch configuration and index lifecycle policies.

Test Alerts

Test alerts (triggered via the admin console) are marked with isTest: true and can be filtered out:

search=isTest != true

---

Error Responses

Status Code	Description
400	Invalid search query syntax
401	Invalid or expired API key
500	Internal server error

---

Related Topics

• Create Alert - Configure alerts that generate logs
• List Alerts - View alert definitions
• ConvertSearch - Build queries programmatically
• Activities API - Query the activities that triggered alerts
• Query Language - Full search syntax reference