> ## 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. # Create a metric alert > Creates a durable metric read and notification publish delegation. Requires telemetry:CreateAlert on the named alert, telemetry:ReadMetrics for the account, and notifications:Publish on the selected topic. Firing and resolved transitions use the topic’s confirmed email, webhook and queue subscriptions. Events are stored atomically with state changes and retried with stable message IDs. Missing data and evaluation errors are visible states, not recovery notifications. ## OpenAPI ````yaml /api-reference/specs/telemetry.yaml post /v1/alerts openapi: 3.0.3 info: title: Basaltic Telemetry API version: 1.0.0 description: > Regional telemetry API — log groups and log ingest/search, metrics (remote_write ingestion and native structured JSON queries), span ingest, and trace search/detail + per-account trace settings. Log-group request references accept UUIDs, CRNs or exact account-scoped names, classified by syntax without lookup fallback. CRNs must match the authenticated account handle and serving region. HTTP and gRPC OTLP logs use basaltic.log_group, falling back to service.name, with the same reference contract. Trace/span identifiers, metric labels and region search dimensions are protocol values, independent of resource resolution. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://telemetry.{region}.basaltic.sh description: Regional API endpoint (one per region) variables: region: default: sa-saopaulo-1 description: Region code security: - BearerAuth: [] paths: /v1/alerts: post: tags: - Telemetry summary: Create a metric alert description: >- Creates a durable metric read and notification publish delegation. Requires telemetry:CreateAlert on the named alert, telemetry:ReadMetrics for the account, and notifications:Publish on the selected topic. Firing and resolved transitions use the topic’s confirmed email, webhook and queue subscriptions. Events are stored atomically with state changes and retried with stable message IDs. Missing data and evaluation errors are visible states, not recovery notifications. operationId: createAlert parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAlertRequest' responses: '201': description: Create a metric alert 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: >- Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token. 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: >- Immutable account-unique name. UUID names and the crn: prefix are reserved. topic: type: string description: >- Required same-account, same-region notification topic reference: UUID, canonical CRN or exact name, classified by syntax. Multiple alerts may share a topic. Binding requires notifications:Publish and respects explicit topic-policy denies. 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: >- Whole-minute window. Evaluated every minute against the last complete UTC-aligned window. for_seconds: type: integer minimum: 0 maximum: 86400 multipleOf: 60 description: >- Continuous breach duration before firing; 0 fires immediately. Missing data, query failures and scheduling gaps reset a pending duration. enabled: type: boolean default: true silenced_until: type: string format: date-time nullable: true description: >- Mute notifications until this instant (at most 30 days ahead). Evaluation continues; null removes silence. An active alert notifies on the next evaluation after silence expires. 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: >- Label matchers (label=value, label!=value, label=~regex, label!~regex). Tenant scope is always applied independently. by: type: array maxItems: 10 items: type: string description: >- Grouping labels; the resulting series are summed to match the console metric card. denominator: $ref: '#/components/schemas/AlertQuery' scale: type: number format: double minimum: 0 exclusiveMinimum: true maximum: 1000000000000 description: >- Multiplier after optional division, e.g. 100 for a percentage or 1/1048576 for MiB/s. unit: type: string maxLength: 32 description: Display unit for the scaled threshold and value. 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: >- Whole-minute window. Evaluated every minute against the last complete UTC-aligned window. for_seconds: type: integer minimum: 0 maximum: 86400 multipleOf: 60 description: >- Continuous breach duration before firing; 0 fires immediately. Missing data, query failures and scheduling gaps reset a pending duration. enabled: type: boolean default: true silenced_until: type: string format: date-time nullable: true description: >- Mute notifications until this instant (at most 30 days ahead). Evaluation continues; null removes silence. An active alert notifies on the next evaluation after silence expires. 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: >- Evaluation state, independent of enabled and silenced_until. Missing data/errors do not resolve an open incident. 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: Notification remains queued for retry; metric evaluation continues. 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: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters params: type: object additionalProperties: true description: >- Optional non-sensitive values for interpolation of localized errors, keyed by error code. Never present for server errors. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Request ID for debugging 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: >- Label matchers (label=value, label!=value, label=~regex, label!~regex). Tenant scope is always applied independently. by: type: array maxItems: 10 items: type: string description: >- Grouping labels; the resulting series are summed to match the console metric card. 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: >- Display label at response time — the resource's name where it has one, otherwise its human label (an invoice number, an account display name). Absent when the target is gone. Not a lookup key. example: Brazil responses: BadRequest: description: Invalid request parameters 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: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions 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: Resource not found 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: Resource conflict (e.g., already exists, invalid state) 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: Internal server error 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: | An OAuth 2.0 bearer token, sent as `Authorization: Bearer `. This is the recommended way to authenticate. Get one by exchanging a service account's access key pair at `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the standard client-credentials grant, so any OAuth-aware library will obtain and refresh it for you. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Tokens last an hour by default. The same access key pair is separately your AWS SigV4 credential for the S3-compatible object endpoint, which speaks nothing else. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.