Skip to main content
POST
Create Alert Definition

Authorizations

Authorization
string
header
required

Use Tuner API key (tr_api_...) or user session token. Find your API key in Workspace Settings > API Keys.

Path Parameters

agent_id
string
required

Tuner's numeric agent ID, or your Agent ID from Agent Settings > Agent Connection. Digits-only values are read as the numeric ID.

workspace_id
integer
required

Workspace ID. Find this in Workspace > General Settings.

Body

application/json

Schema for creating an alert definition.

name
string
required

Alert name

Required string length: 1 - 200
Example:

"Repeated failed identity checks"

window_ms
integer
required

Rolling time window in milliseconds (e.g. 300000 for 5 minutes).

Example:

300000

recipients
string<email>[]
required

List of email recipients

Minimum array length: 1
Example:
notification_channels
enum<string>[]
required

Channels to notify on: email and/or webhook. Selecting webhook requires the agent to have a webhook URL configured.

Minimum array length: 1

Notification channels available for alert definitions.

Available options:
email,
webhook
Example:
condition_tree
ConditionTreeGroup · object
required

Condition a call must match. The root is always a group (AND or OR) of predicates and nested groups, even for a single condition, and every node needs a type (group or predicate). Groups nest at most 10 levels deep, and a tree holds at most 50 conditions.

Examples:
description
string | null

Optional alert description

Example:

"Notify the support team when identity checks keep failing."

severity
enum<string>
default:info

Alert severity level

Available options:
info,
warning,
critical
Example:

"warning"

state
enum<string>
default:active

Alert state (active or paused)

Available options:
active,
paused
Example:

"active"

cooldown_ms
integer
default:900000

Cooldown period in milliseconds (e.g. 900000 for 15 minutes).

Example:

900000

threshold_n
integer | null

Number of qualifying calls to trigger alert. Required when threshold_type='count'.

Required range: x > 0
Example:

5

threshold_type
enum<string>
default:count

Threshold mode: 'count' (absolute) or 'percentage' (ratio of evaluated calls). With 'percentage', the condition tree must be a single predicate.

Available options:
count,
percentage
Example:

"count"

threshold_percentage
number | null

Required when threshold_type='percentage': percentage threshold (0 < x <= 100)

Required range: 0 < x <= 100
Example:

20

threshold_minimum
integer | null

Required when threshold_type='percentage': minimum qualifying calls before alert fires (hard gate)

Required range: x > 0
Example:

10

Response

Successful Response

Response schema for an alert definition.

id
integer
required

Tuner's ID for this alert definition.

Example:

4

agent_id
integer
required

Agent this alert belongs to.

Example:

17

name
string
required

Display name, used in notifications.

Example:

"High red-flag rate"

severity
string
required

Severity label included in notifications.

Example:

"warning"

state
string
required

active when the alert can fire, paused when it can't. An alert paused with a paused_reason needs its condition fixed before it can be set back to active.

Example:

"active"

window_ms
integer
required

Rolling window in milliseconds. 300000 is five minutes.

Example:

300000

cooldown_ms
integer
required

Minimum time in milliseconds before this alert can fire again.

Example:

900000

recipients
string[]
required

Email addresses notified when the alert fires.

Example:
notification_channels
string[]
required

Where notifications are sent.

Example:
condition_tree
Condition Tree · object
required

Condition a call must match to count toward the threshold. For predicates on an eval or a data extraction field, lhs is the field's current name.

Example:
created_at
string<date-time>
required

When the alert was created.

Example:

"2026-07-14T09:22:31Z"

updated_at
string<date-time>
required

When the alert was last updated.

Example:

"2026-07-20T11:40:08Z"

description
string | null

Note explaining what this alert watches for.

paused_reason
string | null

Why Tuner paused this alert, such as Eval deleted when an eval its condition used was deleted. Null when it is active or a person paused it.

Example:

null

threshold_type
string
default:count

count fires on an absolute number of matching calls, percentage on a share of the calls evaluated in the window.

Example:

"percentage"

threshold_n
integer | null

Matching calls needed to fire. Set in count mode.

threshold_percentage
number | null

Share of evaluated calls needed to fire. Set in percentage mode.

Example:

20

threshold_minimum
integer | null

Minimum matching calls before the percentage is applied. Set in percentage mode.

Example:

10

last_triggered
string<date-time> | null

When this alert last fired. Null if it never has.

Example:

"2026-07-31T14:05:12Z"

created_by
integer | null

User who created the alert.

updated_by
integer | null

User who last updated it.