Rules & Alerts

This section covers the management of Rules, retrieving Alerts, and performing historical evaluations using the Falkonry API.

Jupyter Notebook tutorials

• Create basic threshold rules

List rules

Retrieves a list of rules within a specific account. This can be used to browse all rules or search for a specific rule by name.

Method	Path
GET	/api/1.3/accounts/{account_id}/assessments

Query Parameters

Parameter	Type	Required	Description
assessmentType	string	Yes	Must be set to RULE.
name	string	No	Filters by name (contains match). Use double quotes for exact match.
offset	integer	No	Starting index for pagination (Default: 0).
limit	integer	No	Number of items per page (Default: 10).

Usage Examples

cURLPython

curl -H "Authorization: Bearer <token>" \\
"https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/assessments?assessmentType=RULE&offset=0&limit=10&name=Temperature"

import requests

URL = "https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/assessments"
params = {
    "assessmentType": "RULE",
    "offset": 0,
    "limit": 10,
    "name": "Temperature"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.get(URL, headers=headers, params=params)
print(response.json())

---

Retrieve a rule

Retrieves detailed information for a specific rule using its ID.

Method	Path
GET	/api/1.3/accounts/{account_id}/assessments/{rule_id}

Usage Examples

cURLPython

curl -H "Authorization: Bearer <token>" \\
"https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/assessments/{RULE_ID}"

import requests

URL = "https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/assessments/{RULE_ID}"
headers = {"Authorization": "Bearer <token>"}

response = requests.get(URL, headers=headers)
print(response.json())

---

Create a rule

Creates a new rule-based model flow. Use this to define logic across input signals to trigger alerts.

Method	Path
POST	/api/1.3/accounts/{account_id}/flows

Request Body Fields

Field	Type	Description
name	string	Name for the flow.
flowType	string	Must be MODELSETUP.
spec.modelType	string	Must be RULE.
spec.inputschema	array	Mapping of signal names and value types.
spec.modelDetails	object	Configuration including statistic, expression, and evaluationWindow.

Usage Examples

cURLPython

curl -X POST "https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/flows" \\
     -H "Authorization: Bearer <token>" \\
     -H "Content-Type: application/json" \\
     -d '{
      "name": "High Temperature Rule",
      "flowType": "MODELSETUP",
      "spec": {
        "workspace": "ws_12345",
        "modelType": "RULE",
        "inputschema": [{"name":"sensor1", "valueType": "Numeric"}],
        "modelDetails": {
          "statistic": "max",
          "expression": {"condition": ">=", "value": 10},
          "alertFrequency": "PT1H",
          "valueType": "Numeric",
          "evaluationWindow": "PT10M",
          "coverage": 70,
          "density": 85
        }
      }
    }'

import requests

URL = "https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/flows"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
payload = {
    "name": "High Temperature Rule",
    "flowType": "MODELSETUP",
    "spec": {
        "workspace": "ws_12345",
        "modelType": "RULE",
        "inputschema": [{"name": "sensor1", "valueType": "Numeric"}],
        "modelDetails": {
            "statistic": "max",
            "expression": {"condition": ">=", "value": 10},
            "alertFrequency": "PT1H",
            "valueType": "Numeric",
            "evaluationWindow": "PT10M",
            "coverage": 70,
            "density": 85
        }
    }
}

response = requests.post(url=URL, json=payload, headers=headers)
print(response.json())

---

Evaluate a rule

The Rule Evaluation API allows you to apply a specific Rule Model to historical data. This process generates output signals (alerts and explanations) based on the input signals and time range provided.

You can choose to either create new output signals using a prefix or map the evaluation to existing output signals.

Method	Path
POST	/api/1.3/accounts/{account_id}/flows

Request Body Fields

Field	Type	Required	Description
name	string	Yes	A user-defined name for this evaluation task.
flowType	string	Yes	Must be set to RULEEVAL.
description	string	No	A short summary of the evaluation purpose.
spec	object	Yes	Specifications for the evaluation.
spec.model	string	Yes	The ID of the rule model to be evaluated.
spec.workspace	string	Yes	The ID of the workspace where the evaluation results will be stored.
spec.timeRange	object	Yes	Contains startTime and endTime in ISO8601 format.
spec.inputsignals	array	Yes	A list of objects containing signal (Connected Source ID) and name (matching the model schema). The inputsignals array must match the model's input schema.
spec.outputsignalPrefix	string	Conditional*	Mandatory if outputsignals is not provided. Used as a prefix for newly created signals. The evaluation will generate new Connected Sources using the format {{prefix}}/{{model_output_name}}. If a signal with that exact name already exists, the flow will reuse it.
spec.assessmentRate	string	No	ISO duration (e.g., PT5M). If provided, it overrides the value stored in the model configuration. This value also determines the granularity (level) used to load input data for the evaluation.

Usage Examples

cURLPython

curl -X POST \"[https://app3.falkonry.ai/api/1.3/accounts/](https://app3.falkonry.ai/api/1.3/accounts/){ACCOUNT_ID}/flows\" \\
     -H \"Authorization: Bearer <token>\" \\
     -H \"Content-Type: application/json\" \\
     -d '{
      \"name\": \"Eval Test - New Signals\",
      \"flowType\": \"RULEEVAL\",
      \"spec\": {
        \"model\": \"model_id_123\",
        \"workspace\": \"ws_id_456\",
        \"timeRange\": {
          \"startTime\": \"2026-01-01T00:00:00Z\",
          \"endTime\": \"2026-01-02T00:00:00Z\"
        },
        \"inputsignals\": [
          { \"signal\": \"cs_id_001\", \"name\": \"sensor1\" },
          { \"signal\": \"cs_id_002\", \"name\": \"sensor2\" }
        ],
        \"outputsignalPrefix\": \"evaluation/batch1\"
      }
    }'

import requests

URL = "https://app3.falkonry.ai/api/1.3/accounts/{ACCOUNT_ID}/flows"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

payload = {
    "name": "Historical Rule Eval",
    "flowType": "RULEEVAL",
    "spec": {
        "model": "rule_model_id",
        "workspace": "workspace_id",
        "timeRange": {
            "startTime": "2026-01-01T00:00:00Z",
            "endTime": "2026-01-02T00:00:00Z"
        },
        "inputsignals": [
            { "signal": "signal_1_id", "name": "sensor1" },
            { "signal": "signal_2_id", "name": "sensor2" }
        ],
        "outputsignalPrefix": "historical/test_run"
    }
}

response = requests.post(URL, json=payload, headers=headers)
print(response.json())

Note

New output signals are only created if a outputsignalPrefix is used and existing signals with the generated names are not found.

---

Retrieve alerts

Retrieves alerts generated by all rules within an account.

Method	Path
GET	/api/1.3/data/accounts/{account_id}/connectedsources/{account_id}.000000002.alerts/raw_data

Query Parameters

Parameter	Type	Required	Description
start	string	Yes	ISO8601 or nanosecond start time.
end	string	No	ISO8601 or nanosecond end time.
reverse	boolean	No	Set true for descending order (Default: false).

Usage Examples

cURLPython

curl -H "Authorization: Bearer <token>" -H "Accept: application/json" \\
"https://app3.falkonry.ai/api/1.3/data/accounts/{ACCOUNT_ID}/connectedsources/{ACCOUNT_ID}.000000002.alerts/raw_data?start=2025-07-15T22:20:47Z"

import requests

URL = "https://app3.falkonry.ai/api/1.3/data/accounts/{ACCOUNT_ID}/connectedsources/{ACCOUNT_ID}.000000002.alerts/raw_data"
headers = {"Authorization": "Bearer <token>", "Accept": "application/json"}
params = {"start": "2025-07-15T22:20:47Z"}

response = requests.get(URL, headers=headers, params=params)
print(response.json())

Note

The signal field in the response represents the Rule ID. The value field indicates if the condition was met (true).

---

Retreive rule explanation signals

Retrieves the underlying data that explains why an alert was triggered.

Method	Path
GET	/api/1.3/data/accounts/{account_id}/assessments/{rule_id}/explain

Query Parameters

Parameter	Type	Required	Description
time	string	Yes	The timestamp of the alert to explain.

Usage Examples

cURLPython

curl -H "Authorization: Bearer <token>" -H "Accept: application/json" \\
"https://app3.falkonry.ai/api/1.3/data/accounts/{ACCOUNT_ID}/assessments/{RULE_ID}/explain?time=2025-07-16T19:05:00Z"

import requests

URL = f"https://app3.falkonry.ai/api/1.3/data/accounts/{ACCOUNT_ID}/assessments/{RULE_ID}/explain"
headers = {"Authorization": "Bearer <token>", "Accept": "application/json"}
params = {"time": "2025-07-16T19:05:00Z"}

response = requests.get(URL, headers=headers, params=params)
print(response.json())

---