> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Crear una alerta de métrica > Crea una delegación persistente para leer métricas y publicar notificaciones. Requiere telemetry:CreateAlert en la alerta nombrada, telemetry:ReadMetrics en la cuenta y notifications:Publish en el tema seleccionado. Las transiciones de disparo y resolución usan las suscripciones confirmadas de correo, webhook y cola del tema. Los eventos se almacenan atómicamente con los cambios de estado y se reintentan con IDs de mensaje estables. Los datos ausentes y los errores de evaluación son estados visibles, no notificaciones de recuperación. ## OpenAPI ````yaml /es/api-reference/specs/telemetry.yaml post /v1/alerts openapi: 3.0.3 info: title: API de telemetría basaltica version: 1.0.0 description: > API regional de telemetría: grupos de logs, ingesta y búsqueda de logs, ingesta remote_write, consultas estructuradas de métricas en JSON, spans, búsqueda y detalles de trazas y configuración por cuenta. Las referencias de grupos de logs aceptan UUID, CRN o nombre exacto en la cuenta, clasificados por sintaxis sin búsqueda alternativa. Los CRN deben corresponder a la cuenta autenticada y la región. Los logs OTLP HTTP y gRPC usan basaltic.log_group o service.name con el mismo contrato. Los identificadores de trazas y spans, las etiquetas de métricas y las regiones de búsqueda son valores de protocolo independientes de la resolución de recursos. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://telemetry.{region}.basaltic.sh description: Endpoint de API regional (uno por región) variables: region: default: sa-saopaulo-1 description: Código de región security: - BearerAuth: [] paths: /v1/alerts: post: tags: - Telemetry summary: Crear una alerta de métrica description: >- Crea una delegación persistente para leer métricas y publicar notificaciones. Requiere telemetry:CreateAlert en la alerta nombrada, telemetry:ReadMetrics en la cuenta y notifications:Publish en el tema seleccionado. Las transiciones de disparo y resolución usan las suscripciones confirmadas de correo, webhook y cola del tema. Los eventos se almacenan atómicamente con los cambios de estado y se reintentan con IDs de mensaje estables. Los datos ausentes y los errores de evaluación son estados visibles, no notificaciones de recuperación. operationId: createAlert parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAlertRequest' responses: '201': description: Crear una alerta de métrica content: application/json: schema: $ref: '#/components/schemas/AlertResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Clave opcional generada por el cliente que hace que una creación sea segura para la reproducción. Al volver a intentar una solicitud con la misma clave, se devuelve el resultado original literalmente en lugar de crear un recurso duplicado. Se rechaza la reutilización de una clave con un cuerpo de solicitud diferente (422); una solicitud cuya clave todavía se está procesando devuelve 409. Los registros se mantienen durante 24 horas. Usa un UUID o un token único similar. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateAlertRequest: type: object additionalProperties: false required: - name - topic - expression - operator - threshold - window_seconds - for_seconds properties: name: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$ description: >- Nombre inmutable y único en la cuenta. Los nombres UUID y el prefijo crn: están reservados. topic: type: string description: >- Referencia obligatoria a un tema de notificación de la misma cuenta y región: UUID, CRN canónico o nombre exacto, clasificado por sintaxis. Varias alertas pueden compartir un tema. La vinculación requiere notifications:Publish y respeta las denegaciones explícitas de la política del tema. expression: $ref: '#/components/schemas/AlertExpression' operator: type: string enum: - gt - gte - lt - lte threshold: type: number format: double window_seconds: type: integer minimum: 60 maximum: 3600 multipleOf: 60 description: >- Ventana de minutos enteros. Se evalúa cada minuto usando la última ventana completa alineada con UTC. for_seconds: type: integer minimum: 0 maximum: 86400 multipleOf: 60 description: >- Duración continua del incumplimiento antes del disparo; 0 dispara inmediatamente. Los datos ausentes, los fallos de consulta y los intervalos sin evaluación reinician la duración pendiente. enabled: type: boolean default: true silenced_until: type: string format: date-time nullable: true description: >- Silencia las notificaciones hasta este instante (como máximo 30 días en el futuro). La evaluación continúa; null elimina el silencio. Una alerta activa notifica en la siguiente evaluación después de que expire el silencio. AlertResponse: type: object required: - alert properties: alert: $ref: '#/components/schemas/Alert' AlertExpression: type: object additionalProperties: false required: - metric - agg - scale properties: metric: type: string maxLength: 256 pattern: ^[a-zA-Z_:][a-zA-Z0-9_:]*$ agg: type: string enum: - avg - min - max - sum - last - count - rate - increase match: type: array maxItems: 40 items: type: string description: >- Filtros de etiqueta (label=value, label!=value, label=~regex, label!~regex). El ámbito del inquilino siempre se aplica de forma independiente. by: type: array maxItems: 10 items: type: string description: >- Etiquetas de agrupación; las series resultantes se suman para coincidir con la tarjeta de métrica de la consola. denominator: $ref: '#/components/schemas/AlertQuery' scale: type: number format: double minimum: 0 exclusiveMinimum: true maximum: 1000000000000 description: >- Multiplicador después de la división opcional, por ejemplo, 100 para un porcentaje o 1/1048576 para MiB/s. unit: type: string maxLength: 32 description: >- Unidad de visualización del umbral y del valor después de aplicar la escala. Alert: type: object required: - id - crn - name - topic - expression - operator - threshold - window_seconds - for_seconds - enabled - silenced_until - state - last_value - created_at - updated_at properties: expression: $ref: '#/components/schemas/AlertExpression' operator: type: string enum: - gt - gte - lt - lte threshold: type: number format: double window_seconds: type: integer minimum: 60 maximum: 3600 multipleOf: 60 description: >- Ventana de minutos enteros. Se evalúa cada minuto usando la última ventana completa alineada con UTC. for_seconds: type: integer minimum: 0 maximum: 86400 multipleOf: 60 description: >- Duración continua del incumplimiento antes del disparo; 0 dispara inmediatamente. Los datos ausentes, los fallos de consulta y los intervalos sin evaluación reinician la duración pendiente. enabled: type: boolean default: true silenced_until: type: string format: date-time nullable: true description: >- Silencia las notificaciones hasta este instante (como máximo 30 días en el futuro). La evaluación continúa; null elimina el silencio. Una alerta activa notifica en la siguiente evaluación después de que expire el silencio. id: type: string format: uuid crn: type: string example: crn:telemetry:sa-saopaulo-1:my-account:alert/high-cpu name: type: string topic: $ref: '#/components/schemas/ResourceRef' state: type: string enum: - ok - pending - firing - no_data - error description: >- Estado de evaluación, independiente de enabled y silenced_until. Los datos ausentes o los errores no resuelven un incidente abierto. last_value: type: number format: double nullable: true evaluated_at: type: string format: date-time state_changed_at: type: string format: date-time pending_since: type: string format: date-time evaluation_error: type: string delivery_error: type: string description: >- La notificación permanece en cola para reintentarse; la evaluación de la métrica continúa. created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Código de error que identifica el tipo de error example: INVALID_INPUT message: type: string description: Mensaje de error legible por el ser humano example: Invalid request parameters params: type: object additionalProperties: true description: >- Valores no sensibles opcionales para la interpolación de errores localizados, codificados por código de error. Nunca presente por errores del servidor. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Solicitar ID para depuración example: 550e8400-e29b-41d4-a716-446655440000 AlertQuery: type: object additionalProperties: false required: - metric - agg properties: metric: type: string maxLength: 256 pattern: ^[a-zA-Z_:][a-zA-Z0-9_:]*$ agg: type: string enum: - avg - min - max - sum - last - count - rate - increase match: type: array maxItems: 40 items: type: string description: >- Filtros de etiqueta (label=value, label!=value, label=~regex, label!~regex). El ámbito del inquilino siempre se aplica de forma independiente. by: type: array maxItems: 10 items: type: string description: >- Etiquetas de agrupación; las series resultantes se suman para coincidir con la tarjeta de métrica de la consola. ResourceRef: type: object required: - id - crn properties: id: type: string format: uuid example: 288aa1e9-bbf5-5584-bce9-6a688f06d8a1 crn: type: string example: crn:catalog::platform:country/288aa1e9-bbf5-5584-bce9-6a688f06d8a1 name: type: string description: >- Etiqueta en el momento de la respuesta: el nombre del recurso, si lo tiene, o su etiqueta legible (número de factura, nombre de visualización de la cuenta). Ausente cuando el destino ya no existe. No es una clave de búsqueda. example: Brazil responses: BadRequest: description: Parámetros de solicitud no válidos content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 Unauthorized: description: Se requiere autenticación o el token no es válido content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Permisos insuficientes content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 NotFound: description: No se encontró el recurso content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found request_id: 550e8400-e29b-41d4-a716-446655440000 Conflict: description: Conflicto de recursos (por ejemplo, ya existe, estado no válido) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CONFLICT message: Resource with this name already exists request_id: 550e8400-e29b-41d4-a716-446655440000 InternalServerError: description: Error interno del servidor content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >+ Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer `. Esta es la forma recomendada de autenticación. Obtén el token intercambiando el par de claves de acceso de una cuenta de servicio en `POST /v1/oauth/token` con `grant_type=client_credentials`. Es el flujo estándar de credenciales de cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar el token por ti. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Los tokens duran una hora por defecto. El mismo par de claves de acceso también sirve como credencial AWS SigV4 para el endpoint de objetos compatible con S3, que solo acepta ese método de autenticación. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.