🔒Security Requirements and Controls
🎯API Stability
Long-TermThis API is stable and will remain supported across versions with minimal breaking changes.

Summary

The createAggregateAlert() mutation creates an aggregate alert in a LogScale view. An aggregate alert monitors query results over a defined time window and triggers configured actions when the results meet specified conditions. Use updateAggregateAlertV2() to modify an existing aggregate alert after creation.

Syntax

graphql
createAggregateAlert(
      input: CreateAggregateAlert!
   ): AggregateAlert!

The mutation accepts a single required argument, input, of type CreateAggregateAlert!. The input specifies the view name, query string, trigger conditions, and actions to execute when the alert fires. See the Input Parameters section for all available fields.

On success, the mutation returns an AggregateAlert! object representing the newly created alert. The return type is non-null. See the Returned Values section for the available fields.

Example

Raw
graphql
mutation {
  createAggregateAlert(input:
        {viewName: "humio", 
         name: "watch-for-sneak",
         queryString: "@host=*sneak*"
         actionIdsOrNames: "email-admin",
         throttleTimeSeconds: 100, searchIntervalSeconds: 18000,
         queryTimestampType: EventTimestamp,
         queryOwnershipType: Organization
        } )
  { id, name }
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  createAggregateAlert(input:
        {viewName: \"humio\", 
         name: \"watch-for-sneak\",
         queryString: \"@host=*sneak*\"
         actionIdsOrNames: \"email-admin\",
         throttleTimeSeconds: 100, searchIntervalSeconds: 18000,
         queryTimestampType: EventTimestamp,
         queryOwnershipType: Organization
        } )
  { id, name }
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  createAggregateAlert(input:
        {viewName: \"humio\", 
         name: \"watch-for-sneak\",
         queryString: \"@host=*sneak*\"
         actionIdsOrNames: \"email-admin\",
         throttleTimeSeconds: 100, searchIntervalSeconds: 18000,
         queryTimestampType: EventTimestamp,
         queryOwnershipType: Organization
        } )
  { id, name }
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  createAggregateAlert(input: ^
        {viewName: \"humio\",  ^
         name: \"watch-for-sneak\", ^
         queryString: \"@host=*sneak*\" ^
         actionIdsOrNames: \"email-admin\", ^
         throttleTimeSeconds: 100, searchIntervalSeconds: 18000, ^
         queryTimestampType: EventTimestamp, ^
         queryOwnershipType: Organization ^
        } ) ^
  { id, name } ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  createAggregateAlert(input:
        {viewName: \"humio\", 
         name: \"watch-for-sneak\",
         queryString: \"@host=*sneak*\"
         actionIdsOrNames: \"email-admin\",
         throttleTimeSeconds: 100, searchIntervalSeconds: 18000,
         queryTimestampType: EventTimestamp,
         queryOwnershipType: Organization
        } )
  { id, name }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  createAggregateAlert(input:
        {viewName: \"humio\", 
         name: \"watch-for-sneak\",
         queryString: \"@host=*sneak*\"
         actionIdsOrNames: \"email-admin\",
         throttleTimeSeconds: 100, searchIntervalSeconds: 18000,
         queryTimestampType: EventTimestamp,
         queryOwnershipType: Organization
        } )
  { id, name }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  createAggregateAlert(input:
        {viewName: \"humio\", 
         name: \"watch-for-sneak\",
         queryString: \"@host=*sneak*\"
         actionIdsOrNames: \"email-admin\",
         throttleTimeSeconds: 100, searchIntervalSeconds: 18000,
         queryTimestampType: EventTimestamp,
         queryOwnershipType: Organization
        } )
  { id, name }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  createAggregateAlert(input:
        {viewName: \"humio\", 
         name: \"watch-for-sneak\",
         queryString: \"@host=*sneak*\"
         actionIdsOrNames: \"email-admin\",
         throttleTimeSeconds: 100, searchIntervalSeconds: 18000,
         queryTimestampType: EventTimestamp,
         queryOwnershipType: Organization
        } )
  { id, name }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();

Input Parameters

The input argument requires the name of the view associated with the aggregate alert, the query string to execute, and the actions to trigger when the alert fires. The following table describes all fields of the CreateAggregateAlert input type:

Table: CreateAggregateAlert Input Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
actionIdsOrNamesStringyes Long-Term List of unique identifiers or names for actions to fire on query result. Actions in packages can be referred to as packagescope/packagename:actionname. The default value is an empty list of actions.
descriptionString  Long-Term Description of the aggregate alert.
enabledBoolean  Long-Term Flag indicating whether the aggregate alert is enabled.
labelsStringyes Long-Term Labels attached to the aggregate alert. The default value is an empty list of labels.
nameStringyes Long-Term Name of the aggregate alert.
queryOwnershipTypeQueryOwnershipTypeyes Long-Term Ownership of the query run by this aggregate alert. If value is User, ownership will be based on the runAsUserId field. See QueryOwnershipType.
queryStringStringyes Long-Term The LogScale query to execute.
queryTimestampTypeQueryTimestampTypeyes Long-Term Timestamp type to use for a query. See QueryTimestampType.
runAsUserIdString  Long-Term The aggregate alert will run with the permissions of the user corresponding to this id if the queryOwnershipType field is set to User. If the queryOwnershipType is set to Organization, whilst runAsUserId is set, this will result in an error. If not specified, the aggregate alert will run with the permissions of the calling user. It requires the ChangeTriggersToRunAsOtherUsers permission to set this field to a user id different from the calling user.
searchIntervalSecondsLongyes Long-Term Search interval in seconds. Valid values: 1-80 minutes in seconds divisible by 60 (60, 120, ..., 4800 seconds); 82-180 minutes in seconds divisible by 120 (4920, 5040, ..., 10800 seconds); and 4-24 hours in seconds divisible by 3600 (14400, 18000, ..., 86400 seconds).
throttleFieldString  Deprecateddeprecated in 1.282The field on which to throttle. This can be set only if throttleTimeSeconds is set. Aggregate alerts now support multiple throttle fields. This field will be removed at the earliest in version 1.279. Use instead the throttleFields field.
throttleFieldsStringyes Long-Term The fields on which to throttle. This can be set only if throttleTimeSeconds is set. Ten throttle fields can be added at most.
throttleTimeSecondsLongyes Long-Term Throttle time in seconds.
triggerModeTriggerMode  Long-Term Trigger mode used for triggering the alert. See TriggerMode.
viewNameRepoOrViewNameyes Long-Term Name of the view of the aggregate alert. RepoOrViewName is a scalar.

Returned Values

The mutation returns an AggregateAlert object representing the newly created alert. The returned fields include the alert's unique identifier, query string, configured actions, trigger mode, and enabled status. You can use the returned identifier to reference the alert in subsequent updateAggregateAlertV2(), enableAggregateAlertV2(), disableAggregateAlertV2(), or deleteAggregateAlertV2() calls.

Table: AggregateAlert Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
actionsActionyes Long-Term List of actions to fire on query result. See Action.
allowedActionsAssetActionyes Short-Term List of actions allowed to fire on query result. See AssetAction .
createdInfoAssetCommitMetadata  Long-Term Metadata related to the creation of the aggregate alert. See AssetCommitMetadata.
descriptionString  Long-Term Description of the aggregate alert.
enabledBooleanyes Long-Term Flag indicating whether the aggregate alert is enabled.
idStringyes Long-Term Unique identifier of of the aggregate alert.
labelsStringyes Long-Term Labels attached to the aggregate alert.
lastErrorString  Long-Term Last error encountered while running the aggregate alert.
lastSuccessfulPollLong  Long-Term Unix timestamp for last successful poll of the aggregate alert query. If this isn't very recent, the alert might have problems.
lastTriggeredLong  Long-Term Unix timestamp for last execution of trigger.
lastWarningsStringyes Long-Term Last warnings encountered while running the aggregate alert.
modifiedInfoModifiedInfoyes Long-Term User or token used to modify the asset. See ModifiedInfo.
nameStringyes Long-Term Name of the aggregate alert.
packagePackageInstallation  Long-Term The package of which the aggregate alert was installed. See PackageInstallation.
packageIdVersionedPackageSpecifier  Long-Term The unique identifier of the package of the aggregate alert template. VersionedPackageSpecifier is a scalar.
queryOwnershipQueryOwnershipyes Long-Term Ownership of the query run by this alert. See QueryOwnership.
queryStringStringyes Long-Term LogScale query to execute.
queryTimestampTypeQueryTimestampTypeyes Long-Term Timestamp type to use for a query. See QueryTimestampType and the FAQ: How to handle ingest delays in aggregate alerts and scheduled searches KB article.
resourceStringyes Short-Term The resource identifier for the aggregate alert.
searchIntervalSecondsLongyes Long-Term Search interval in seconds.
throttleFieldString  Deprecateddeprecated in 1.282The field on which to throttle. This can be set only if throttleTimeSeconds is set. Aggregate alerts now support multiple throttle fields. This field will be removed at the earliest in version 1.279. Use instead the throttleFields field.
throttleFieldsStringyes Long-Term The fields on which to throttle. This can be set only if throttleTimeSeconds is set.
throttleTimeSecondsLongyes Long-Term Throttle time in seconds.
triggerModeTriggerModeyes Long-Term Trigger mode used for triggering the alert. See TriggerMode and the FAQ: How to handle ingest delays in aggregate alerts and scheduled searches KB article.
yamlTemplateYAMLyes Long-Term The yaml specification of the aggregate alert. YAML is a scalar.