> ## Documentation Index > Fetch the complete documentation index at: https://docs.usetuner.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Alert Definition > Create a new alert definition for an agent. An alert fires when its condition matches enough calls within a rolling window. `threshold_type` decides which threshold fields are required: `count` needs `threshold_n`, `percentage` needs both `threshold_percentage` and `threshold_minimum`. `condition_tree` must have a group at its root and contain at least one predicate. With `percentage`, the tree is limited to a single predicate. Selecting `webhook` in `notification_channels` requires the agent to have a webhook URL configured. ## OpenAPI ````yaml https://api.usetuner.ai/public/openapi.json post /api/v1/workspaces/{workspace_id}/agents/{agent_id}/settings/alert-definitions openapi: 3.1.0 info: title: My Public API version: 1.0.0 servers: - url: https://api.usetuner.ai security: [] tags: - name: calls x-group: Calls - name: workspaces x-group: Workspaces - name: agent-settings x-group: Agent Settings - name: agents x-group: Agents - name: simulation x-group: Simulation - name: providers x-group: Providers paths: /api/v1/workspaces/{workspace_id}/agents/{agent_id}/settings/alert-definitions: post: tags: - agent-settings summary: Create Alert Definition description: >- Create a new alert definition for an agent. An alert fires when its condition matches enough calls within a rolling window. `threshold_type` decides which threshold fields are required: `count` needs `threshold_n`, `percentage` needs both `threshold_percentage` and `threshold_minimum`. `condition_tree` must have a group at its root and contain at least one predicate. With `percentage`, the tree is limited to a single predicate. Selecting `webhook` in `notification_channels` requires the agent to have a webhook URL configured. operationId: >- create_alert_definition_api_v1_workspaces__workspace_id__agents__agent_id__settings_alert_definitions_post parameters: - name: agent_id in: path required: true schema: type: integer description: Tuner's internal numeric ID for the agent. title: Agent Id description: Tuner's internal numeric ID for the agent. - name: workspace_id in: path required: true schema: type: integer description: Workspace ID. Find this in Workspace > General Settings. title: Workspace Id description: Workspace ID. Find this in Workspace > General Settings. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AlertDefinitionCreate' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AlertDefinitionResponse' '401': description: Missing or invalid API key. content: application/json: example: detail: Not authenticated schema: $ref: '#/components/schemas/ErrorResponse' '403': description: You do not have access to this workspace. content: application/json: example: detail: User does not have access to workspace 42 schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Agent not found. content: application/json: example: detail: Agent with ID 17 not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- Either 'webhook' was selected as a notification channel but the agent has no webhook_url configured, or threshold_type is missing one of its required companion fields (threshold_n for 'count'; threshold_percentage and threshold_minimum for 'percentage'). content: application/json: example: detail: >- Agent has no webhook URL configured. Add one in Agent Settings > Webhooks before enabling webhook alerts. schema: $ref: '#/components/schemas/ErrorResponse' security: - Bearer: [] components: schemas: AlertDefinitionCreate: properties: name: type: string maxLength: 200 minLength: 1 title: Name description: Alert name description: anyOf: - type: string - type: 'null' title: Description description: Optional alert description severity: $ref: '#/components/schemas/AlertSeverity' description: Alert severity level default: info state: $ref: '#/components/schemas/AlertState' description: Alert state (active or paused) default: active window_ms: type: integer exclusiveMinimum: 0 title: Window Ms description: >- Rolling time window in milliseconds (e.g. 300000 for 5 minutes). Client must send ms; frontend converts from seconds/minutes for UX. cooldown_ms: type: integer exclusiveMinimum: 0 title: Cooldown Ms description: >- Cooldown period in milliseconds (e.g. 900000 for 15 minutes). Client must send ms; frontend converts for UX. default: 900000 threshold_n: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' title: Threshold N description: >- Number of qualifying calls to trigger alert. Required when threshold_type='count'. threshold_type: $ref: '#/components/schemas/ThresholdType' description: >- Threshold mode: 'count' (absolute) or 'percentage' (ratio of evaluated calls) default: count threshold_percentage: anyOf: - type: number maximum: 100 exclusiveMinimum: 0 - type: 'null' title: Threshold Percentage description: >- Required when threshold_type='percentage': percentage threshold (0 < x <= 100) threshold_minimum: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' title: Threshold Minimum description: >- Required when threshold_type='percentage': minimum qualifying calls before alert fires (hard gate) recipients: items: type: string format: email type: array minItems: 1 title: Recipients description: List of email recipients notification_channels: items: $ref: '#/components/schemas/NotificationChannel' type: array minItems: 1 title: Notification Channels description: 'Channels to notify on: email and/or webhook' condition_tree: $ref: '#/components/schemas/ConditionTreeGroup' description: >- Condition tree (root must always be a group node, even for single conditions) type: object required: - name - window_ms - recipients - notification_channels - condition_tree title: AlertDefinitionCreate description: Schema for creating an alert definition. AlertDefinitionResponse: properties: id: type: integer title: Id description: Tuner's ID for this alert definition. examples: - 4 agent_id: type: integer title: Agent Id description: Agent this alert belongs to. examples: - 17 name: type: string title: Name description: Display name, used in notifications. examples: - High red-flag rate description: anyOf: - type: string - type: 'null' title: Description description: Note explaining what this alert watches for. severity: type: string title: Severity description: Severity label included in notifications. examples: - warning state: type: string title: State description: '`active` when the alert can fire, `paused` when it can''t.' examples: - active window_ms: type: integer title: Window Ms description: Rolling window in milliseconds. 300000 is five minutes. examples: - 300000 cooldown_ms: type: integer title: Cooldown Ms description: Minimum time in milliseconds before this alert can fire again. examples: - 900000 threshold_type: type: string title: Threshold Type description: >- `count` fires on an absolute number of matching calls, `percentage` on a share of the calls evaluated in the window. default: count examples: - percentage threshold_n: anyOf: - type: integer - type: 'null' title: Threshold N description: Matching calls needed to fire. Set in `count` mode. threshold_percentage: anyOf: - type: number - type: 'null' title: Threshold Percentage description: Share of evaluated calls needed to fire. Set in `percentage` mode. examples: - 20 threshold_minimum: anyOf: - type: integer - type: 'null' title: Threshold Minimum description: >- Minimum matching calls before the percentage is applied. Set in `percentage` mode. examples: - 10 recipients: items: type: string type: array title: Recipients description: Email addresses notified when the alert fires. examples: - - oncall@acme.com notification_channels: items: type: string type: array title: Notification Channels description: Where notifications are sent. examples: - - email condition_tree: additionalProperties: true type: object title: Condition Tree description: Condition a call must match to count toward the threshold. examples: - children: - lhs: eval.12 op: eq rhs: FAIL type: predicate op: AND type: group last_triggered: anyOf: - type: string format: date-time - type: 'null' title: Last Triggered description: When this alert last fired. Null if it never has. examples: - '2026-07-31T14:05:12Z' created_at: type: string format: date-time title: Created At description: When the alert was created. examples: - '2026-07-14T09:22:31Z' updated_at: type: string format: date-time title: Updated At description: When the alert was last updated. examples: - '2026-07-20T11:40:08Z' created_by: anyOf: - type: integer - type: 'null' title: Created By description: User who created the alert. updated_by: anyOf: - type: integer - type: 'null' title: Updated By description: User who last updated it. type: object required: - id - agent_id - name - severity - state - window_ms - cooldown_ms - recipients - notification_channels - condition_tree - created_at - updated_at title: AlertDefinitionResponse description: Response schema for an alert definition. ErrorResponse: properties: detail: type: string title: Detail description: Human-readable description of what went wrong. type: object required: - detail title: ErrorResponse description: Error body returned when a request fails. AlertSeverity: type: string enum: - info - warning - critical title: AlertSeverity description: Alert severity levels. AlertState: type: string enum: - active - paused title: AlertState description: Alert state values. ThresholdType: type: string enum: - count - percentage title: ThresholdType description: Threshold mode for alert definitions. NotificationChannel: type: string enum: - email - webhook title: NotificationChannel description: Notification channels available for alert definitions. ConditionTreeGroup: properties: type: type: string const: group title: Type description: Marks this node as a group of conditions. default: group id: anyOf: - type: string - type: 'null' title: Id description: Optional ID for UI op: $ref: '#/components/schemas/LogicalOperator' description: Whether all children must match (`AND`) or any (`OR`). children: items: anyOf: - $ref: '#/components/schemas/ConditionTreeGroup' - $ref: '#/components/schemas/ConditionTreePredicate' type: array minItems: 1 title: Children description: Nested groups or predicates. type: object required: - op - children title: ConditionTreeGroup description: Group node in condition tree. LogicalOperator: type: string enum: - AND - OR title: LogicalOperator description: Logical operators for group nodes. ConditionTreePredicate: properties: type: type: string const: predicate title: Type description: Marks this node as a single condition. default: predicate id: anyOf: - type: string - type: 'null' title: Id description: Optional ID for UI lhs: type: string title: Lhs description: Field or metric to evaluate, from List Alert Conditions. op: $ref: '#/components/schemas/ComparisonOperator' description: How to compare `lhs` to `rhs`. rhs: anyOf: - {} - type: 'null' title: Rhs description: Value to compare against. Omit for `exists` and `not_exists`. type: object required: - lhs - op title: ConditionTreePredicate description: Predicate node in condition tree. ComparisonOperator: type: string enum: - eq - neq - gt - gte - lt - lte - exists - not_exists - contains - starts_with title: ComparisonOperator description: Comparison operators for predicate nodes. securitySchemes: Bearer: type: http description: >- Use Tuner API key (tr_api_...) or user session token. Find your API key in Workspace Settings > API Keys. scheme: bearer ````