On this page
alerts.create
Create an alert rule on a metered usage or run metric
Request
POST /api/v1/alerts
- MCP:
alerts_create - SDK:
client.alerts.create(SDK path arguments usepath; MCP usesparams). - Minimum API key role: admin.
- Idempotency: required_header. Send an
Idempotency-Keyheader; MCP usesidempotency_key. Reuse it after an unknown outcome.
Use the request schema below. Read IDs from earlier operation results.
Input schema
json
{
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertsCreateRequest"
}
}
}
}
}
Responses
json
{
"201": {
"description": "Create an alert rule on a metered usage or run metric",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AlertsAcknowledgeResponse200"
}
}
}
},
"4XX": {
"description": "Typed error (ApiError)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"5XX": {
"description": "Typed error (ApiError)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
Referenced schemas
json
{
"components": {
"schemas": {
"AlertsCreateRequest": {
"type": "object",
"properties": {
"metric": {
"type": "string",
"enum": [
"spend_usd_per_hour",
"p95_latency_ms_1h",
"call_error_rate_24h",
"recording_failure_rate_24h"
]
},
"threshold": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,12})?$"
},
"enabled": {
"type": "boolean"
},
"destination": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"slack"
]
}
},
"required": [
"kind"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"pagerduty"
]
}
},
"required": [
"kind"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"webhook"
]
},
"url": {
"type": "string",
"format": "uri",
"maxLength": 4096
}
},
"required": [
"kind",
"url"
],
"additionalProperties": false
}
]
}
},
"required": [
"metric",
"threshold",
"enabled",
"destination"
],
"additionalProperties": false
},
"AlertsAcknowledgeResponse200": {
"type": "object",
"properties": {
"scope": {
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"tenant_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"owner_id",
"environment",
"tenant_id"
],
"additionalProperties": false
},
"rule": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"revision": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
},
"metric": {
"type": "string",
"minLength": 1
},
"threshold": {
"type": "string",
"minLength": 1
},
"destination": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"slack",
"pagerduty",
"webhook",
"unsupported"
]
}
},
"required": [
"kind"
],
"additionalProperties": false
},
"enabled": {
"type": "boolean"
},
"deleted_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"evaluation": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"pending",
"available",
"unavailable"
]
},
"reason": {
"type": "string",
"enum": [
"no_observations",
"incomplete_usage",
"incomplete_coverage",
"metric_unavailable",
"unsupported_metric",
"destination_unavailable",
"unsupported_destination",
"invalid_rule"
],
"nullable": true
},
"evaluated_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"window": {
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
}
},
"required": [
"from",
"to"
],
"additionalProperties": false,
"nullable": true
},
"value": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,12})?$",
"nullable": true
},
"evidence": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"usage_view"
]
},
"view": {
"type": "object",
"properties": {
"schema_version": {
"type": "string",
"enum": [
"1"
]
},
"scope": {
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"tenant_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"owner_id",
"environment",
"tenant_id"
],
"additionalProperties": false
},
"window": {
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
},
"as_of": {
"type": "string",
"format": "date-time"
},
"snapshot": {
"type": "string",
"maxLength": 4096,
"pattern": "^[0-9]+:[0-9]+:(?:[0-9]+(?:,[0-9]+)*)?$"
},
"cohort": {
"type": "object",
"properties": {
"observation_count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"observation_count",
"sha256"
],
"additionalProperties": false
}
},
"required": [
"schema_version",
"scope",
"window",
"as_of",
"snapshot",
"cohort"
],
"additionalProperties": false
},
"basis": {
"type": "string",
"enum": [
"declared_estimate"
]
},
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"coverage": {
"type": "string",
"enum": [
"recorded_measurements_only"
]
},
"observation_count": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
}
},
"required": [
"kind",
"view",
"basis",
"currency",
"coverage",
"observation_count"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"usage_statement"
]
},
"statement_id": {
"type": "string",
"format": "uuid"
},
"basis": {
"type": "string",
"enum": [
"declared_estimate"
]
},
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"coverage": {
"type": "string",
"enum": [
"recorded_measurements_only"
]
},
"observation_count": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
}
},
"required": [
"kind",
"statement_id",
"basis",
"currency",
"coverage",
"observation_count"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"gateway_attempt_latency"
]
},
"observation_count": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
}
},
"required": [
"kind",
"observation_count"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"talos_metric"
]
},
"metric": {
"type": "string",
"enum": [
"call_error_rate_24h",
"recording_failure_rate_24h"
]
},
"definition_version": {
"type": "number",
"enum": [
1
]
},
"observation_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"failed_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"unknown_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"kind",
"metric",
"definition_version",
"observation_count",
"failed_count",
"unknown_count"
],
"additionalProperties": false
}
],
"nullable": true
}
},
"required": [
"status",
"reason",
"evaluated_at",
"window",
"value",
"evidence"
],
"additionalProperties": false
},
"last_fired_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"blocked_by_delivery_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"latest_delivery": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"rule_revision": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
},
"status": {
"type": "string",
"enum": [
"pending",
"sending",
"delivered",
"cancelled",
"uncertain"
]
},
"destination_kind": {
"type": "string",
"enum": [
"slack",
"pagerduty",
"webhook"
]
},
"destination_revision": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,12})?$"
},
"threshold": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,12})?$"
},
"window": {
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
},
"evidence": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"usage_view"
]
},
"view": {
"type": "object",
"properties": {
"schema_version": {
"type": "string",
"enum": [
"1"
]
},
"scope": {
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"tenant_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"owner_id",
"environment",
"tenant_id"
],
"additionalProperties": false
},
"window": {
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
},
"as_of": {
"type": "string",
"format": "date-time"
},
"snapshot": {
"type": "string",
"maxLength": 4096,
"pattern": "^[0-9]+:[0-9]+:(?:[0-9]+(?:,[0-9]+)*)?$"
},
"cohort": {
"type": "object",
"properties": {
"observation_count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"observation_count",
"sha256"
],
"additionalProperties": false
}
},
"required": [
"schema_version",
"scope",
"window",
"as_of",
"snapshot",
"cohort"
],
"additionalProperties": false
},
"basis": {
"type": "string",
"enum": [
"declared_estimate"
]
},
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"coverage": {
"type": "string",
"enum": [
"recorded_measurements_only"
]
},
"observation_count": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
}
},
"required": [
"kind",
"view",
"basis",
"currency",
"coverage",
"observation_count"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"usage_statement"
]
},
"statement_id": {
"type": "string",
"format": "uuid"
},
"basis": {
"type": "string",
"enum": [
"declared_estimate"
]
},
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"coverage": {
"type": "string",
"enum": [
"recorded_measurements_only"
]
},
"observation_count": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
}
},
"required": [
"kind",
"statement_id",
"basis",
"currency",
"coverage",
"observation_count"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"gateway_attempt_latency"
]
},
"observation_count": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
}
},
"required": [
"kind",
"observation_count"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"talos_metric"
]
},
"metric": {
"type": "string",
"enum": [
"call_error_rate_24h",
"recording_failure_rate_24h"
]
},
"definition_version": {
"type": "number",
"enum": [
1
]
},
"observation_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"failed_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"unknown_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"kind",
"metric",
"definition_version",
"observation_count",
"failed_count",
"unknown_count"
],
"additionalProperties": false
}
],
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"send_intent_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"finished_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"error_code": {
"type": "string",
"minLength": 1,
"nullable": true
},
"acknowledged_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"id",
"rule_revision",
"status",
"destination_kind",
"destination_revision",
"value",
"threshold",
"window",
"evidence",
"created_at",
"send_intent_at",
"finished_at",
"error_code",
"acknowledged_at"
],
"additionalProperties": false,
"nullable": true
}
},
"required": [
"id",
"revision",
"metric",
"threshold",
"destination",
"enabled",
"deleted_at",
"evaluation",
"last_fired_at",
"blocked_by_delivery_id",
"latest_delivery"
],
"additionalProperties": false
}
},
"required": [
"scope",
"rule"
],
"additionalProperties": false
},
"ApiError": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"unauthenticated",
"forbidden",
"not_found",
"conflict",
"invalid_request",
"idempotency_conflict",
"policy_denied",
"capability_unavailable",
"provider_unavailable",
"knowledge_unavailable",
"publication_invalid",
"run_not_active",
"rate_limited",
"outcome_unknown",
"internal"
]
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"outcome": {
"type": "string",
"enum": [
"none",
"unknown"
]
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"code",
"message",
"retryable",
"outcome"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
Errors and recovery
See API error handling and Troubleshooting.
Related guides
Content version 30ce0d1bMarkdown source