> ## Documentation Index > Fetch the complete documentation index at: https://docs.corbado.com/llms.txt > Use this file to discover all available pages before exploring further. # List alert instances > Lists Observe alert instances for the project. Paginated; newest-evaluated first unless orderBy says otherwise. Empty until the alerting evaluator runs. Required API key permission: `observe:alerts:read`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml get /observe/alertInstances openapi: 3.1.1 info: version: 1.0.0 title: Corbado API description: > # Introduction This documentation gives an overview of all Corbado API calls to implement authentication observe. contact: name: Corbado team email: support@corbado.com url: https://www.corbado.com servers: - url: https://api.cloud.corbado.io/v1 security: - bearerAuth: [] tags: - name: ObserveFlow description: Flow search and related APIs x-group: Journeys and users - name: ObserveSubFlow description: Subflow search and related APIs x-group: Journeys and users - name: ObserveUser description: User search and related APIs x-group: Journeys and users - name: ObserveClientEnv description: Client environment search APIs x-group: Journeys and users - name: ObserveTimeSeries description: Time series query APIs x-group: Metrics and funnels - name: ObserveFunnel description: Historical funnel metrics, dictionaries and coverage. x-group: Metrics and funnels - name: ObserveEvent description: Event ingestion and event feed APIs x-group: Events - name: ObserveError description: Named authentication errors and recommendations. x-group: Error management - name: ObserveErrorFlavour description: Error variants and their impact on authentication outcomes. x-group: Error management - name: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: Annotation APIs (dated notes for analytics context) x-group: Annotations - name: ObserveTableExport description: Table export file listing and download APIs x-group: Data exports - name: ObserveTimeSeriesExport description: Time-series export generation and downloads. x-group: Data exports - name: ObserveDataExport description: Data export APIs x-group: User data - name: ObserveDataDeletionJob description: Data deletion job APIs x-group: User data - name: ObserveFlowTypeDefinition description: Flow type definitions used in authentication journeys. x-group: Catalogs and labels - name: ObserveCatalog description: Catalog APIs x-group: Catalogs and labels - name: OpenAPI description: Downloadable API specification - name: ProjectOperationExecution description: Project-scoped operation history and pipeline health - name: ObserveClassification description: Flow and subflow classification APIs - name: ObserveIntegrationStats description: Integration stats APIs - name: ObserveTimeSeriesPrecalculation description: Time series precalculation APIs - name: ObserveIDList x-group: Saved ID lists description: Stored ID-list selection APIs - name: ObserveDataContext description: Schema-loose data context APIs for agent and debugging tooling - name: ObserveData description: Observe data administration APIs - name: ObserveTrackingStats description: Tracking ingestion stats APIs - name: ObserveExperiment x-group: Experiments description: Experiment catalog and run APIs - name: ObserveDataPolicy description: >- Project data policy catalogue (retention selected by the SDK's meta.dataPolicy code) - name: ObserveMetadata x-group: Metadata description: Authenticator metadata APIs (FIDO MDS + passkey AAGUID) - name: ObservePasskey x-group: Passkey analysis description: Observed passkey search and cohort analysis. paths: /observe/alertInstances: get: tags: - ObserveAlert summary: List alert instances description: >- Lists Observe alert instances for the project. Paginated; newest-evaluated first unless orderBy says otherwise. Empty until the alerting evaluator runs. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertInstanceList parameters: - name: alertRuleID in: query required: false description: Filter to instances of a single alert rule (format `aru-`). schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=aru - name: alertInstanceID in: query required: false description: >- Filter to a single alert instance (format `ain-`), so an alert email can deep-link to exactly the alert it names. schema: type: string x-oapi-codegen-extra-tags: validate: omitempty,id=ain - name: status in: query required: false description: > Filter by instance status - comma-separated, and read as "or". A set rather than one value because the panel's status cards are a multi-select: asking for firing and pending separately would page the two answers independently and leave them impossible to merge into one ordered list. style: form explode: false schema: type: array maxItems: 5 items: type: string enum: - normal - pending - firing - no_data - error x-oapi-codegen-extra-tags: validate: >- omitempty,max=5,unique,dive,oneof=normal pending firing no_data error - name: ruleName in: query required: false description: > Filter to alerts whose rule's name contains this text, so one search box can serve both the rules list and the flat alert list. It filters and does not project: the alerts that come back carry their rule's id, as they always do, and not its name. schema: type: string maxLength: 255 x-oapi-codegen-extra-tags: validate: omitempty,max=255 - name: orderBy in: query required: false description: > Field to order by. lastEvaluated, the default, is the order the panel's lists open in; the others are the columns those lists can be sorted on. status orders by urgency (normal, no_data, error, pending, firing) and severity by level (info, warning, critical) rather than alphabetically, so descending puts the alert that needs attention first; ties within such a column resolve newest-evaluated first. An instance with no value for the field - never notified, no severity yet - sorts as the lowest. schema: type: string default: lastEvaluated enum: - lastEvaluated - status - severity - currentValue - lastStatusChange - lastNotification x-oapi-codegen-extra-tags: validate: >- omitempty,oneof=lastEvaluated status severity currentValue lastStatusChange lastNotification - name: orderDirection in: query required: false description: Order direction. schema: type: string default: desc enum: - asc - desc x-oapi-codegen-extra-tags: validate: omitempty,oneof=asc desc - name: page in: query description: | The page number to retrieve for paginated results. required: false schema: type: integer default: 1 example: 1 - name: pageSize in: query description: | The number of items to return per page. Useful for pagination. required: false schema: type: integer default: 10 example: 20 responses: '200': description: >- Paginated list of alert instances. Paging metadata is returned in X-Corbado-Page, X-Corbado-TotalPages, and X-Corbado-TotalItems response headers. content: application/json: schema: type: array maxItems: 1000 items: $ref: '#/components/schemas/observeAlertInstance' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:alerts:read components: schemas: observeAlertInstance: type: object required: - id - alertRuleID - alertRuleName - labelSetHash - hasOverride - status - createdMs - updatedMs properties: id: type: string description: Alert instance ID (format `ain-`). alertRuleID: type: string description: Alert rule ID (format `aru-`). alertRuleName: type: string description: > Name of the rule this alert belongs to, resolved from alertRuleID so an alert can be displayed without a second request. Display-only - requests still reference the rule by alertRuleID. labelSetHash: type: string labels: type: object additionalProperties: type: string currentValue: type: number format: double thresholdValue: type: number format: double hasOverride: type: boolean description: > Whether this alert is judged by one of its rule's overrides rather than by the rule's own values, as of the rule's current configuration. firstBreachedMs: type: integer format: int64 lastEvaluatedMs: type: integer format: int64 lastStatusChangeMs: type: integer format: int64 lastNotificationMs: type: integer format: int64 errorMessage: type: string severity: type: string enum: - info - warning - critical description: > The severity band matched at the last evaluation, absent when none matched. Status says whether the instance is firing, level says how badly, and the two move independently. The level is deliberately not part of labelSetHash - an identity that moved with the level would fork one incident into two. highWaterSeverity: type: string enum: - info - warning - critical description: > The most severe level this firing episode has already notified at, reset when the instance returns to normal. It is why a de-escalation is silent and why a re-escalation below this mark does not mail again: an instance notifies once per level per episode, and only ever as things get worse. noDataReason: type: string enum: - no_data - division_by_zero - guard_not_met - too_many_instances - rule_changed - dimension_not_available - series_not_available description: > Why this instance has no value, absent when it has one. The first three come from the rule type - no rows at all, an empty denominator, or a group under the sample gate - and the rest from the framework: the rule produced more groups than maxInstances, its grouping was edited, a dimension it groups by is gone from the project, or the series it reads is no longer available for the project. Missing, zero and errored stay three distinct things, so a group with no logins never reads as a 0% success rate. createdMs: type: integer format: int64 updatedMs: type: integer format: int64 previousStatus: type: string enum: - normal - pending - firing - no_data - error status: type: string enum: - normal - pending - firing - no_data - error errorRspV2: type: object required: - error properties: error: type: object required: - message properties: message: description: Error message type: string example: Validation failed details: description: Validation error details per field type: array items: type: object required: - field - message properties: field: description: Field name that failed validation type: string example: projectID message: description: Validation error message type: string example: required responses: error: description: Error content: application/json: schema: $ref: '#/components/schemas/errorRspV2' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Use an Observe API key from the management console. The key selects the project and must grant the permission listed on the operation. Keep this key on your server. ````