Scheduled Alerts

Overview

The Confident AI SDK exposes every Scheduled Alert method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

List Scheduled Alerts

Lists the scheduled alerts in your Confident AI project one page at a time, ordered by name, as summary rows.

from confident_ai import ConfidentAI
from confident_ai.scheduled_alerts import AlertDataModel

client = ConfidentAI()

result = client.scheduled_alerts.list(
    page=1,
    page_size=25,
    data_model=AlertDataModel.TRACE,
    enabled="true",
)

For async mode, call a_list and await it as shown below:

result = await client.scheduled_alerts.a_list(...)

Parameters

Parameter	Type	Description
`page`	`Optional[int]`	The page of scheduled alerts to return. Defaults to 1.
`page_size`	`Optional[int]`	The number of scheduled alerts per page, at most 100. Defaults to 25.
`data_model`	`Optional[AlertDataModel]`	Returns only alerts measuring this kind of item. Omit to return all of them. See AlertDataModel.
`enabled`	`Optional[Literal['true', 'false']]`	Returns only alerts whose schedule is running when `true`, or only the paused ones when `false`. Omit to return both.

import { ConfidentAI } from "confident-ai";
import { AlertDataModel } from "confident-ai/scheduled-alerts";

const client = new ConfidentAI();

const result = await client.scheduledAlerts.list(
  {
    page: 1,
    pageSize: 25,
    dataModel: AlertDataModel.TRACE,
    enabled: "true"
  },
);

Parameters

Parameter	Type	Description
`page`	`number`	The page of scheduled alerts to return. Defaults to 1.
`pageSize`	`number`	The number of scheduled alerts per page, at most 100. Defaults to 25.
`dataModel`	`AlertDataModel`	Returns only alerts measuring this kind of item. Omit to return all of them. See AlertDataModel.
`enabled`	`"true" \| "false"`	Returns only alerts whose schedule is running when `true`, or only the paused ones when `false`. Omit to return both.

Returns

This method returns an object of type ScheduledAlertList.

Create Scheduled Alert

Creates an alert that re-runs an aggregate query on a schedule and notifies when the result crosses the threshold, and returns its id. Notifications are delivered through the project's integrations that have alerting enabled for the alert's severity, so an alert in a project with no such integration still evaluates but reaches nobody.

from confident_ai import ConfidentAI
from confident_ai.scheduled_alerts import AlertDataModel
from confident_ai.scheduled_alerts import AlertSeverity
from confident_ai.scheduled_alerts import AlertThresholdDirection
from confident_ai.scheduled_alerts import AlertThresholdSettings
from confident_ai.common import ScheduleIntervalUnit
from confident_ai.common import ScheduleRecurrenceType

client = ConfidentAI()

result = client.scheduled_alerts.create(
    name="Trace error rate spike",
    data_model=AlertDataModel.TRACE,
    aggregation="ERROR_RATE",
    threshold_settings=AlertThresholdSettings(
        value=0.05,
        direction=AlertThresholdDirection.ABOVE
    ),
    recurrence=ScheduleRecurrenceType.ONCE,
    repeat_every=1,
    repeat_unit=ScheduleIntervalUnit.MINUTE,
    start_at="2025-02-01T09:00:00+00:00",
    max_runs=12,
    end_at="2025-12-31T23:59:59+00:00",
    description="Errors above 5% over the last hour.",
    filters={
        "operator": "AND",
        "groups": [
            {
                "operator": "AND",
                "filters": [
                    {
                        "category": "Trace Name",
                        "condition": "Is",
                        "value": "checkout"
                    }
                ]
            }
        ]
    },
    severity=AlertSeverity.CRITICAL,
    enabled=True,
)

For async mode, call a_create and await it as shown below:

result = await client.scheduled_alerts.a_create(...)

Parameters

Parameter	Type	Description
`name`	`str`	Required. A name for the alert, shown in the notification.
`data_model`	`AlertDataModel`	Required. See AlertDataModel.
`aggregation`	`str`	Required. What to measure, as an aggregation token. Which tokens are valid depends on `dataModel`: `TRACE` accepts COUNT, ERROR_RATE, PASS_RATE, UNIQUE_END_USERS, UNIQUE_THREADS, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, INPUT_TOKENS, OUTPUT_TOKENS, TOTAL_TOKENS, UNIQUE_METADATA_VALUES; `LLM_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, INPUT_TOKENS, OUTPUT_TOKENS, TOTAL_TOKENS, UNIQUE_METADATA_VALUES; `AGENT_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `RETRIEVER_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `TOOL_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `CUSTOM_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `THREAD` accepts COUNT, UNIQUE_USERS, UNIQUE_METADATA_VALUES.
`threshold_settings`	`AlertThresholdSettings`	Required. See AlertThresholdSettings.
`recurrence`	`Optional[ScheduleRecurrenceType]`	See ScheduleRecurrenceType.
`repeat_every`	`Optional[int]`	How many `repeatUnit`s apart the runs are, for an INTERVAL schedule. Send null to clear it.
`repeat_unit`	`Optional[ScheduleIntervalUnit]`	The unit `repeatEvery` counts, for an INTERVAL schedule. Send null to clear it. See ScheduleIntervalUnit.
`start_at`	`Optional[str]`	When the schedule first runs, as an ISO 8601 datetime. Send null to start it immediately.
`max_runs`	`Optional[int]`	How many times the schedule runs before it stops. Send null to let it run indefinitely.
`end_at`	`Optional[str]`	When the schedule stops running, as an ISO 8601 datetime. Send null to leave it open-ended.
`description`	`Optional[str]`	What the alert means and what to do about it, included in the notification. Send null to clear it.
`filters`	`Optional[FilterSet]`	Narrows what the alert measures over, so an alert can watch one route rather than the whole project. Send null to clear the filters and measure everything. See FilterSet.
`severity`	`Optional[AlertSeverity]`	See AlertSeverity.
`enabled`	`Optional[bool]`	Whether the schedule runs. Defaults to true.

import { ConfidentAI } from "confident-ai";
import {
  ScheduleIntervalUnit,
  ScheduleRecurrenceType,
} from "confident-ai/common";
import {
  AlertDataModel,
  AlertSeverity,
  AlertThresholdDirection,
} from "confident-ai/scheduled-alerts";

const client = new ConfidentAI();

const result = await client.scheduledAlerts.create(
  "Trace error rate spike",
  AlertDataModel.TRACE,
  "ERROR_RATE",
  {
    value: 0.05,
    direction: AlertThresholdDirection.ABOVE
  },
  {
    recurrence: ScheduleRecurrenceType.ONCE,
    repeatEvery: 1,
    repeatUnit: ScheduleIntervalUnit.MINUTE,
    startAt: "2025-02-01T09:00:00+00:00",
    maxRuns: 12,
    endAt: "2025-12-31T23:59:59+00:00",
    description: "Errors above 5% over the last hour.",
    filters: {
      operator: "AND",
      groups: [
        {
          operator: "AND",
          filters: [{ category: "Trace Name", condition: "Is", value: "checkout" }]
        }
      ]
    },
    severity: AlertSeverity.CRITICAL,
    enabled: true
  },
);

Parameters

Parameter	Type	Description
`name`	`string`	Required. A name for the alert, shown in the notification.
`dataModel`	`AlertDataModel`	Required. See AlertDataModel.
`aggregation`	`string`	Required. What to measure, as an aggregation token. Which tokens are valid depends on `dataModel`: `TRACE` accepts COUNT, ERROR_RATE, PASS_RATE, UNIQUE_END_USERS, UNIQUE_THREADS, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, INPUT_TOKENS, OUTPUT_TOKENS, TOTAL_TOKENS, UNIQUE_METADATA_VALUES; `LLM_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, INPUT_TOKENS, OUTPUT_TOKENS, TOTAL_TOKENS, UNIQUE_METADATA_VALUES; `AGENT_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `RETRIEVER_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `TOOL_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `CUSTOM_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `THREAD` accepts COUNT, UNIQUE_USERS, UNIQUE_METADATA_VALUES.
`thresholdSettings`	`AlertThresholdSettings`	Required. See AlertThresholdSettings.
`recurrence`	`ScheduleRecurrenceType`	See ScheduleRecurrenceType.
`repeatEvery`	`number \| null`	How many `repeatUnit`s apart the runs are, for an INTERVAL schedule. Send null to clear it.
`repeatUnit`	`ScheduleIntervalUnit \| null`	The unit `repeatEvery` counts, for an INTERVAL schedule. Send null to clear it. See ScheduleIntervalUnit.
`startAt`	`string \| null`	When the schedule first runs, as an ISO 8601 datetime. Send null to start it immediately.
`maxRuns`	`number \| null`	How many times the schedule runs before it stops. Send null to let it run indefinitely.
`endAt`	`string \| null`	When the schedule stops running, as an ISO 8601 datetime. Send null to leave it open-ended.
`description`	`string \| null`	What the alert means and what to do about it, included in the notification. Send null to clear it.
`filters`	`FilterSet \| null`	Narrows what the alert measures over, so an alert can watch one route rather than the whole project. Send null to clear the filters and measure everything. See FilterSet.
`severity`	`AlertSeverity`	See AlertSeverity.
`enabled`	`boolean`	Whether the schedule runs. Defaults to true.

Returns

This method returns an object of type ScheduledAlertRef.

Get Scheduled Alert

Retrieves a scheduled alert by id, with its aggregation, filters, threshold, severity and schedule state including how many times it has run.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.scheduled_alerts.get(
    scheduled_alert_id="<SCHEDULED-ALERT-ID>",
)

For async mode, call a_get and await it as shown below:

result = await client.scheduled_alerts.a_get(...)

Parameters

Parameter	Type	Description
`scheduled_alert_id`	`str`	Required. The id of the scheduled alert.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.scheduledAlerts.get("<SCHEDULED-ALERT-ID>");

Parameters

Parameter	Type	Description
`scheduledAlertId`	`string`	Required. The id of the scheduled alert.

Returns

This method returns an object of type ScheduledAlert.

Update Scheduled Alert

Updates a scheduled alert and returns it. Only the fields you send are changed; omitting a field leaves it untouched, and sending null clears it. Because each dataModel accepts a different set of aggregations, send aggregation alongside dataModel when moving an alert between data models.

from confident_ai import ConfidentAI
from confident_ai.scheduled_alerts import AlertDataModel
from confident_ai.scheduled_alerts import AlertSeverity
from confident_ai.scheduled_alerts import AlertThresholdDirection
from confident_ai.scheduled_alerts import AlertThresholdSettings
from confident_ai.common import ScheduleIntervalUnit
from confident_ai.common import ScheduleRecurrenceType

client = ConfidentAI()

result = client.scheduled_alerts.update(
    scheduled_alert_id="<SCHEDULED-ALERT-ID>",
    recurrence=ScheduleRecurrenceType.ONCE,
    repeat_every=1,
    repeat_unit=ScheduleIntervalUnit.MINUTE,
    start_at="2025-02-01T09:00:00+00:00",
    max_runs=12,
    end_at="2025-12-31T23:59:59+00:00",
    description="Errors above 5% over the last hour.",
    filters={
        "operator": "AND",
        "groups": [
            {
                "operator": "AND",
                "filters": [
                    {
                        "category": "Trace Name",
                        "condition": "Is",
                        "value": "checkout"
                    }
                ]
            }
        ]
    },
    severity=AlertSeverity.CRITICAL,
    name="Trace error rate spike",
    data_model=AlertDataModel.TRACE,
    aggregation="ERROR_RATE",
    threshold_settings=AlertThresholdSettings(
        value=0.05,
        direction=AlertThresholdDirection.ABOVE
    ),
    enabled=False,
)

For async mode, call a_update and await it as shown below:

result = await client.scheduled_alerts.a_update(...)

Parameters

Parameter	Type	Description
`scheduled_alert_id`	`str`	Required. The id of the scheduled alert.
`recurrence`	`Optional[ScheduleRecurrenceType]`	See ScheduleRecurrenceType.
`repeat_every`	`Optional[int]`	How many `repeatUnit`s apart the runs are, for an INTERVAL schedule. Send null to clear it.
`repeat_unit`	`Optional[ScheduleIntervalUnit]`	The unit `repeatEvery` counts, for an INTERVAL schedule. Send null to clear it. See ScheduleIntervalUnit.
`start_at`	`Optional[str]`	When the schedule first runs, as an ISO 8601 datetime. Send null to start it immediately.
`max_runs`	`Optional[int]`	How many times the schedule runs before it stops. Send null to let it run indefinitely.
`end_at`	`Optional[str]`	When the schedule stops running, as an ISO 8601 datetime. Send null to leave it open-ended.
`description`	`Optional[str]`	What the alert means and what to do about it, included in the notification. Send null to clear it.
`filters`	`Optional[FilterSet]`	Narrows what the alert measures over, so an alert can watch one route rather than the whole project. Send null to clear the filters and measure everything. See FilterSet.
`severity`	`Optional[AlertSeverity]`	See AlertSeverity.
`name`	`Optional[str]`	A new name for the alert, shown in the notification.
`data_model`	`Optional[AlertDataModel]`	See AlertDataModel.
`aggregation`	`Optional[str]`	What to measure, as an aggregation token. Which tokens are valid depends on `dataModel`: `TRACE` accepts COUNT, ERROR_RATE, PASS_RATE, UNIQUE_END_USERS, UNIQUE_THREADS, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, INPUT_TOKENS, OUTPUT_TOKENS, TOTAL_TOKENS, UNIQUE_METADATA_VALUES; `LLM_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, INPUT_TOKENS, OUTPUT_TOKENS, TOTAL_TOKENS, UNIQUE_METADATA_VALUES; `AGENT_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `RETRIEVER_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `TOOL_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `CUSTOM_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `THREAD` accepts COUNT, UNIQUE_USERS, UNIQUE_METADATA_VALUES.
`threshold_settings`	`Optional[AlertThresholdSettings]`	See AlertThresholdSettings.
`enabled`	`Optional[bool]`	Whether the schedule runs. An alert whose run limit or end date has passed cannot be re-enabled without also moving `maxRuns` or `endAt`.

import { ConfidentAI } from "confident-ai";
import {
  ScheduleIntervalUnit,
  ScheduleRecurrenceType,
} from "confident-ai/common";
import {
  AlertDataModel,
  AlertSeverity,
  AlertThresholdDirection,
} from "confident-ai/scheduled-alerts";

const client = new ConfidentAI();

const result = await client.scheduledAlerts.update(
  "<SCHEDULED-ALERT-ID>",
  {
    recurrence: ScheduleRecurrenceType.ONCE,
    repeatEvery: 1,
    repeatUnit: ScheduleIntervalUnit.MINUTE,
    startAt: "2025-02-01T09:00:00+00:00",
    maxRuns: 12,
    endAt: "2025-12-31T23:59:59+00:00",
    description: "Errors above 5% over the last hour.",
    filters: {
      operator: "AND",
      groups: [
        {
          operator: "AND",
          filters: [{ category: "Trace Name", condition: "Is", value: "checkout" }]
        }
      ]
    },
    severity: AlertSeverity.CRITICAL,
    name: "Trace error rate spike",
    dataModel: AlertDataModel.TRACE,
    aggregation: "ERROR_RATE",
    thresholdSettings: {
      value: 0.05,
      direction: AlertThresholdDirection.ABOVE
    },
    enabled: false
  },
);

Parameters

Parameter	Type	Description
`scheduledAlertId`	`string`	Required. The id of the scheduled alert.
`recurrence`	`ScheduleRecurrenceType`	See ScheduleRecurrenceType.
`repeatEvery`	`number \| null`	How many `repeatUnit`s apart the runs are, for an INTERVAL schedule. Send null to clear it.
`repeatUnit`	`ScheduleIntervalUnit \| null`	The unit `repeatEvery` counts, for an INTERVAL schedule. Send null to clear it. See ScheduleIntervalUnit.
`startAt`	`string \| null`	When the schedule first runs, as an ISO 8601 datetime. Send null to start it immediately.
`maxRuns`	`number \| null`	How many times the schedule runs before it stops. Send null to let it run indefinitely.
`endAt`	`string \| null`	When the schedule stops running, as an ISO 8601 datetime. Send null to leave it open-ended.
`description`	`string \| null`	What the alert means and what to do about it, included in the notification. Send null to clear it.
`filters`	`FilterSet \| null`	Narrows what the alert measures over, so an alert can watch one route rather than the whole project. Send null to clear the filters and measure everything. See FilterSet.
`severity`	`AlertSeverity`	See AlertSeverity.
`name`	`string`	A new name for the alert, shown in the notification.
`dataModel`	`AlertDataModel`	See AlertDataModel.
`aggregation`	`string`	What to measure, as an aggregation token. Which tokens are valid depends on `dataModel`: `TRACE` accepts COUNT, ERROR_RATE, PASS_RATE, UNIQUE_END_USERS, UNIQUE_THREADS, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, INPUT_TOKENS, OUTPUT_TOKENS, TOTAL_TOKENS, UNIQUE_METADATA_VALUES; `LLM_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, INPUT_TOKENS, OUTPUT_TOKENS, TOTAL_TOKENS, UNIQUE_METADATA_VALUES; `AGENT_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `RETRIEVER_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `TOOL_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `CUSTOM_SPAN` accepts COUNT, AVG_LATENCY, P50_LATENCY, P90_LATENCY, P99_LATENCY, ERROR_RATE, ERROR_COUNT, INPUT_COST, OUTPUT_COST, TOTAL_COST, AVG_COST, UNIQUE_METADATA_VALUES; `THREAD` accepts COUNT, UNIQUE_USERS, UNIQUE_METADATA_VALUES.
`thresholdSettings`	`AlertThresholdSettings`	See AlertThresholdSettings.
`enabled`	`boolean`	Whether the schedule runs. An alert whose run limit or end date has passed cannot be re-enabled without also moving `maxRuns` or `endAt`.

Returns

This method returns an object of type ScheduledAlert.

Delete Scheduled Alert

Permanently deletes a scheduled alert and unregisters its next run. To stop an alert temporarily, update it with enabled set to false instead. This action cannot be undone.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.scheduled_alerts.delete(
    scheduled_alert_id="<SCHEDULED-ALERT-ID>",
)

For async mode, call a_delete and await it as shown below:

result = await client.scheduled_alerts.a_delete(...)

Parameters

Parameter	Type	Description
`scheduled_alert_id`	`str`	Required. The id of the scheduled alert.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.scheduledAlerts.delete("<SCHEDULED-ALERT-ID>");

Parameters

Parameter	Type	Description
`scheduledAlertId`	`string`	Required. The id of the scheduled alert.

Returns

This method returns an object of type ScheduledAlertRef.

Types

AlertDataModel

What kind of production item an alert measures over. TRACE and SPAN alerts aggregate single requests; THREAD alerts aggregate conversations.

class AlertDataModel(Enum):
    TRACE = "TRACE"
    SPAN = "SPAN"
    LLM_SPAN = "LLM_SPAN"
    AGENT_SPAN = "AGENT_SPAN"
    RETRIEVER_SPAN = "RETRIEVER_SPAN"
    TOOL_SPAN = "TOOL_SPAN"
    CUSTOM_SPAN = "CUSTOM_SPAN"
    THREAD = "THREAD"

enum AlertDataModel {
  TRACE = "TRACE",
  SPAN = "SPAN",
  LLM_SPAN = "LLM_SPAN",
  AGENT_SPAN = "AGENT_SPAN",
  RETRIEVER_SPAN = "RETRIEVER_SPAN",
  TOOL_SPAN = "TOOL_SPAN",
  CUSTOM_SPAN = "CUSTOM_SPAN",
  THREAD = "THREAD",
}

TRACE · SPAN · LLM_SPAN · AGENT_SPAN · RETRIEVER_SPAN · TOOL_SPAN · CUSTOM_SPAN · THREAD

AlertSeverity

How urgent the alert is. It also decides who hears about it: an integration receives an alert only when it subscribes to that severity.

class AlertSeverity(Enum):
    CRITICAL = "CRITICAL"
    ERROR = "ERROR"
    WARNING = "WARNING"
    INFO = "INFO"

enum AlertSeverity {
  CRITICAL = "CRITICAL",
  ERROR = "ERROR",
  WARNING = "WARNING",
  INFO = "INFO",
}

CRITICAL · ERROR · WARNING · INFO

AlertThresholdDirection

Whether the alert fires when the measured value rises above the threshold or falls below it.

class AlertThresholdDirection(Enum):
    ABOVE = "above"
    BELOW = "below"

enum AlertThresholdDirection {
  ABOVE = "above",
  BELOW = "below",
}

ABOVE · BELOW

AlertThresholdSettings

When the alert fires. Latency is compared in seconds, cost in USD, and rates such as ERROR_RATE as fractions between 0 and 1.

class AlertThresholdSettings:
    value: float
    direction: AlertThresholdDirection

valuefloatRequired

The number the measured value is compared against.

Example: 0.05

directionAlertThresholdDirectionRequired

See AlertThresholdDirection.

interface AlertThresholdSettings {
  value: number;
  direction: AlertThresholdDirection;
}

valuenumberRequired

The number the measured value is compared against.

Example: 0.05

directionAlertThresholdDirectionRequired

See AlertThresholdDirection.

FilterSet

A set of filter groups combined by a top-level operator. Each group combines its filter rows by its own operator, and each row matches one property, such as Name or User Id, against a value with a condition such as Is or Contains.

class FilterSet:
    operator: Literal["AND", "OR"]
    groups: List[FilterSetGroup]

operatorLiteral["AND", "OR"]Required

groupsList[FilterSetGroup]Required

interface FilterSet {
  operator: "AND" | "OR";
  groups: FilterSetGroup[];
}

operator"AND" | "OR"Required

groupsFilterSetGroup[]Required

ScheduleIntervalUnit

The unit repeatEvery counts for an INTERVAL schedule.

class ScheduleIntervalUnit(Enum):
    MINUTE = "MINUTE"
    HOUR = "HOUR"
    DAY = "DAY"
    WEEK = "WEEK"
    MONTH = "MONTH"

enum ScheduleIntervalUnit {
  MINUTE = "MINUTE",
  HOUR = "HOUR",
  DAY = "DAY",
  WEEK = "WEEK",
  MONTH = "MONTH",
}

MINUTE · HOUR · DAY · WEEK · MONTH

ScheduleRecurrenceType

How often a schedule fires: ONCE runs a single time at startAt, INTERVAL repeats every repeatEvery repeatUnits.

class ScheduleRecurrenceType(Enum):
    ONCE = "ONCE"
    INTERVAL = "INTERVAL"

enum ScheduleRecurrenceType {
  ONCE = "ONCE",
  INTERVAL = "INTERVAL",
}

ONCE · INTERVAL

ScheduledAlert

An alert that re-runs an aggregate query on a schedule and notifies when the result crosses its threshold.

class ScheduledAlert:
    id: str
    name: str
    description: Optional[str]
    data_model: AlertDataModel = Field(alias="dataModel")
    aggregation: str
    filters: FilterSet
    threshold_settings: AlertThresholdSettings = Field(alias="thresholdSettings")
    severity: AlertSeverity
    schedule_settings: Optional[ScheduledAlertScheduleSettings] = Field(alias="scheduleSettings")

idstrRequired

The id of the scheduled alert, generated by Confident AI.

Example: "<SCHEDULED-ALERT-ID>"

namestrRequired

The name of the alert, shown in the notification.

Example: "Trace error rate spike"

descriptionOptional[str]Required

What the alert means and what to do about it, or null when it has no description.

Example: "Errors above 5% over the last hour."

data_modelAlertDataModelRequired

See AlertDataModel.

aggregationstrRequired

What the alert measures, as an aggregation token.

Example: "ERROR_RATE"

filtersFilterSetRequired

See FilterSet.

threshold_settingsAlertThresholdSettingsRequired

See AlertThresholdSettings.

severityAlertSeverityRequired

See AlertSeverity.

schedule_settingsOptional[ScheduledAlertScheduleSettings]Required

See ScheduledAlertScheduleSettings.

interface ScheduledAlert {
  id: string;
  name: string;
  description: string | null;
  dataModel: AlertDataModel;
  aggregation: string;
  filters: FilterSet;
  thresholdSettings: AlertThresholdSettings;
  severity: AlertSeverity;
  scheduleSettings: ScheduledAlertScheduleSettings | null;
}

idstringRequired

The id of the scheduled alert, generated by Confident AI.

Example: "<SCHEDULED-ALERT-ID>"

namestringRequired

The name of the alert, shown in the notification.

Example: "Trace error rate spike"

descriptionstring | nullRequired

What the alert means and what to do about it, or null when it has no description.

Example: "Errors above 5% over the last hour."

dataModelAlertDataModelRequired

See AlertDataModel.

aggregationstringRequired

What the alert measures, as an aggregation token.

Example: "ERROR_RATE"

filtersFilterSetRequired

See FilterSet.

thresholdSettingsAlertThresholdSettingsRequired

See AlertThresholdSettings.

severityAlertSeverityRequired

See AlertSeverity.

scheduleSettingsScheduledAlertScheduleSettings | nullRequired

See ScheduledAlertScheduleSettings.

ScheduledAlertList

One page of scheduled alerts, with the total across all pages.

class ScheduledAlertList:
    scheduled_alerts: List[ScheduledAlertSummary] = Field(alias="scheduledAlerts")
    total_scheduled_alerts: int = Field(alias="totalScheduledAlerts")
    page: int
    page_size: int = Field(alias="pageSize")

scheduled_alertsList[ScheduledAlertSummary]Required

The scheduled alerts for the current page, ordered by name.

See ScheduledAlertSummary.

total_scheduled_alertsintRequired

The total number of scheduled alerts matching the filters.

Example: 7

pageintRequired

The page this response covers.

Example: 1

page_sizeintRequired

The number of scheduled alerts per page.

Example: 25

interface ScheduledAlertList {
  scheduledAlerts: ScheduledAlertSummary[];
  totalScheduledAlerts: number;
  page: number;
  pageSize: number;
}

scheduledAlertsScheduledAlertSummary[]Required

The scheduled alerts for the current page, ordered by name.

See ScheduledAlertSummary.

totalScheduledAlertsnumberRequired

The total number of scheduled alerts matching the filters.

Example: 7

pagenumberRequired

The page this response covers.

Example: 1

pageSizenumberRequired

The number of scheduled alerts per page.

Example: 25

ScheduledAlertRef

A reference to a scheduled alert by its id.

class ScheduledAlertRef:
    id: str

idstrRequired

The id of the scheduled alert, generated by Confident AI.

Example: "<SCHEDULED-ALERT-ID>"

interface ScheduledAlertRef {
  id: string;
}

idstringRequired

The id of the scheduled alert, generated by Confident AI.

Example: "<SCHEDULED-ALERT-ID>"

ScheduledAlertScheduleSettings

The alert's cadence together with its run history.

class ScheduledAlertScheduleSettings:
    recurrence: ScheduleRecurrenceType
    repeat_every: Optional[int] = Field(alias="repeatEvery")
    repeat_unit: Optional[ScheduleIntervalUnit] = Field(alias="repeatUnit")
    start_at: Optional[str] = Field(alias="startAt")
    end_at: Optional[str] = Field(alias="endAt")
    max_runs: Optional[int] = Field(alias="maxRuns")
    run_count: int = Field(alias="runCount")
    last_run_at: Optional[str] = Field(alias="lastRunAt")
    enabled: bool

recurrenceScheduleRecurrenceTypeRequired

See ScheduleRecurrenceType.

repeat_everyOptional[int]Required

How many repeatUnits apart the runs are, or null when the alert runs once.

Example: 1

repeat_unitOptional[ScheduleIntervalUnit]Required

See ScheduleIntervalUnit.

start_atOptional[str]Required

When the schedule first runs, or null when it started immediately.

end_atOptional[str]Required

When the schedule stops running, or null when it is open-ended.

max_runsOptional[int]Required

How many times the alert runs before it stops, or null when it runs indefinitely.

run_countintRequired

How many times the alert has run so far.

Example: 12

last_run_atOptional[str]Required

When the alert last ran, or null until its first run.

Example: "2025-02-01T10:00:00+00:00"

enabledboolRequired

Whether the schedule is currently running.

Example: true

interface ScheduledAlertScheduleSettings {
  recurrence: ScheduleRecurrenceType;
  repeatEvery: number | null;
  repeatUnit: ScheduleIntervalUnit | null;
  startAt: string | null;
  endAt: string | null;
  maxRuns: number | null;
  runCount: number;
  lastRunAt: string | null;
  enabled: boolean;
}

recurrenceScheduleRecurrenceTypeRequired

See ScheduleRecurrenceType.

repeatEverynumber | nullRequired

How many repeatUnits apart the runs are, or null when the alert runs once.

Example: 1

repeatUnitScheduleIntervalUnit | nullRequired

See ScheduleIntervalUnit.

startAtstring | nullRequired

When the schedule first runs, or null when it started immediately.

endAtstring | nullRequired

When the schedule stops running, or null when it is open-ended.

maxRunsnumber | nullRequired

How many times the alert runs before it stops, or null when it runs indefinitely.

runCountnumberRequired

How many times the alert has run so far.

Example: 12

lastRunAtstring | nullRequired

When the alert last ran, or null until its first run.

Example: "2025-02-01T10:00:00+00:00"

enabledbooleanRequired

Whether the schedule is currently running.

Example: true

ScheduledAlertSummary

An alert as it appears in a list: what it measures and whether it is running. Retrieve it by id for its aggregation, filters, threshold, severity and run history.

class ScheduledAlertSummary:
    id: str
    name: str
    data_model: AlertDataModel = Field(alias="dataModel")
    enabled: bool

idstrRequired

The id of the scheduled alert, generated by Confident AI.

Example: "<SCHEDULED-ALERT-ID>"

namestrRequired

The name of the alert.

Example: "Trace error rate spike"

data_modelAlertDataModelRequired

See AlertDataModel.

enabledboolRequired

Whether the alert's schedule is running. False when the alert has no schedule.

Example: true

interface ScheduledAlertSummary {
  id: string;
  name: string;
  dataModel: AlertDataModel;
  enabled: boolean;
}

idstringRequired

The id of the scheduled alert, generated by Confident AI.

Example: "<SCHEDULED-ALERT-ID>"

namestringRequired

The name of the alert.

Example: "Trace error rate spike"

dataModelAlertDataModelRequired

See AlertDataModel.

enabledbooleanRequired

Whether the alert's schedule is running. False when the alert has no schedule.

Example: true

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on September 30, 2026

Built byConfident AI