> ## 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. # List metric alerts > Account-scoped keyset pagination by UUID, ascending. Markers are opaque and bound to the account and filters. No tenant identity is included in the response. ## OpenAPI ````yaml /api-reference/specs/telemetry.yaml get /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: get: tags: - Telemetry summary: List metric alerts description: >- Account-scoped keyset pagination by UUID, ascending. Markers are opaque and bound to the account and filters. No tenant identity is included in the response. operationId: listAlerts parameters: - name: name in: query description: Exact name filter; an explicitly empty name matches nothing. schema: type: string - name: crn in: query description: >- Exact canonical alert CRN, intersected with name and state. Empty/malformed CRNs return 400; valid foreign CRNs return an empty page. schema: type: string - name: state in: query description: >- Filter effective state. Disabled takes precedence over silenced; otherwise uses evaluation state. schema: type: string enum: - ok - pending - firing - no_data - error - silenced - disabled - $ref: '#/components/parameters/LimitDefault50' - $ref: '#/components/parameters/Marker' responses: '200': description: List metric alerts content: application/json: schema: $ref: '#/components/schemas/AlertListResponse' '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: LimitDefault50: name: limit in: query description: >- Maximum number of items to return. A value above the maximum is clamped to it rather than rejected, so a page shorter than the one you asked for is normal — page until `meta.has_more` is false, not until a page looks short. required: false schema: type: integer minimum: 1 maximum: 100 default: 50 example: 50 Marker: name: marker in: query description: >- Opaque pagination cursor. Echo back the `meta.marker` value from the previous page to fetch the next one; do not construct or parse it. The token's internal form varies by endpoint (a resource ID, a timestamp, …) and is not guaranteed stable across releases. required: false schema: type: string example: 550e8400-e29b-41d4-a716-446655440000 schemas: AlertListResponse: type: object required: - alerts - meta properties: alerts: type: array items: $ref: '#/components/schemas/Alert' meta: $ref: '#/components/schemas/PaginationMeta' 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 PaginationMeta: type: object properties: total: type: integer description: Total number of items example: 150 limit: type: integer description: Number of items per page example: 20 marker: type: string description: >- Opaque cursor for the next page. Pass it back as the `marker` query parameter; treat it as a token, not a value to parse. example: 550e8400-e29b-41d4-a716-446655440000 has_more: type: boolean description: Whether there are more items example: true 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 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. 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 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. 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.