> ## 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. # Get alert firing > Returns one firing of an alert: from the evaluation that switched it to firing to the one that switched it to another status, with the transitions and notifications in between and the alert's current state. Pass the ID of any transition of the firing: the one that fired it, a severity change, the one that ended it, or the breach that made it pending. The `firingID` of a notification, a phase or an alert is such an ID. The response's `id` is the transition that fired it. Firings are kept as long as their transitions, about 90 days. Required API key permission: `observe:alerts:read`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml get /observe/alertFirings/{alertFiringID} 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: ObserveIdentifier description: Identifier search over submitted identifiers 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: ObserveFinding description: Curated findings that explain errors, their impact and who has to act. x-group: Error management - name: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: >- Annotations, the project's memory (what is true about the data and how to read it) 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: ObserveProbe description: Raw probe capture items (internal autocapture diagnostics) - name: ObserveTelemetry description: Raw SDK/integration diagnostic telemetry - 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/alertFirings/{alertFiringID}: get: tags: - ObserveAlert summary: Get alert firing description: >- Returns one firing of an alert: from the evaluation that switched it to firing to the one that switched it to another status, with the transitions and notifications in between and the alert's current state. Pass the ID of any transition of the firing: the one that fired it, a severity change, the one that ended it, or the breach that made it pending. The `firingID` of a notification, a phase or an alert is such an ID. The response's `id` is the transition that fired it. Firings are kept as long as their transitions, about 90 days. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertFiringGet parameters: - name: alertFiringID in: path required: true description: A transition of the firing (format `atr-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=atr responses: '200': description: The firing. content: application/json: schema: $ref: '#/components/schemas/observeAlertFiring' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:alerts:read components: schemas: observeAlertFiring: type: object description: > One firing of an alert, from the evaluation that switched it to firing to the one that switched it to another status. Severity changes while firing belong to it. An alert that fires again after it ended, also after a stretch without data, starts a new firing. required: - id - alert - firedMs - durationMs - transitions - notifications properties: id: type: string description: The transition that fired the alert (format `atr-`). alert: $ref: '#/components/schemas/observeAlertInstance' pendingSinceMs: type: integer format: int64 description: >- When the breach that led to the firing began. Absent when it fired without a pending period. firedMs: type: integer format: int64 description: When the alert switched to firing. endedMs: type: integer format: int64 description: When the firing ended. Absent while the alert is still firing. endStatus: type: string enum: - normal - pending - no_data - error x-enum-varnames: - ObserveAlertFiringEndStatusNormal - ObserveAlertFiringEndStatusPending - ObserveAlertFiringEndStatusNoData - ObserveAlertFiringEndStatusError description: >- The status the alert switched to when the firing ended. Absent while it is still firing. endReason: type: string description: > Why the firing ended, the reason of the transition that ended it: `recovery`, a no-data reason or `rule_changed`. Absent while it is still firing. durationMs: type: integer format: int64 description: How long the alert was firing, up to now while it still is. transitions: type: array maxItems: 500 description: > The firing's transitions, oldest first: the breach that made it pending, if any, the one that fired it, its severity changes and the one that ended it. items: $ref: '#/components/schemas/observeAlertTransition' notifications: type: array maxItems: 1000 description: What was sent from the start of the firing to its end, oldest first. items: $ref: '#/components/schemas/observeAlertNotification' previousFiringID: type: string description: >- The alert's firing before this one (format `atr-`). Absent when there is none. nextFiringID: type: string description: >- The alert's firing after this one (format `atr-`). Absent when there is none. observeAlertInstance: type: object required: - id - alertRuleID - alertRuleName - ruleType - labelSetHash - hasOverride - status - valueFormat - vocabulary - createdMs - updatedMs properties: id: type: string description: Alert instance ID (format `ain-`). valueFormat: $ref: '#/components/schemas/observeAlertValueFormat' vocabulary: $ref: '#/components/schemas/observeAlertVocabulary' description: > What the alert's rule calls its numbers, resolved from the rule's type and the variant it picks, so a list of alerts across rules names each value the way its rule does. 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. ruleType: type: string enum: - login_success_rate - flow_volume - subflow_volume description: >- Type of the rule this alert belongs to; names what the alert measures and the shape of its evaluation details. 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 - outside_evaluation_hours 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, the series it reads is no longer available for the project, or the evaluation instant is outside the evaluation hours that apply to this instance. outside_evaluation_hours is the one reason that comes with any status, because outside its hours an instance keeps the status it had. 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 currentFiringID: type: string description: >- While the alert is firing, a transition of its current firing (format `atr-`), for `GET /observe/alertFirings/{alertFiringID}`. Absent otherwise. observeAlertTransition: type: object required: - id - alertRuleID - alertInstanceID - toStatus - reason - notified - evaluatedMs - createdMs properties: id: type: string description: Alert transition ID (format `atr-`). alertRuleID: type: string description: Alert rule ID (format `aru-`). alertInstanceID: type: string description: Alert instance ID (format `ain-`). labels: type: object additionalProperties: type: string description: > The label set of the alert instance this row is about, resolved from alertInstanceID so the history can name the alert the way the alert list does. Absent for the ungrouped alert of a rule with no groupBy, which has no labels. fromStatus: type: string enum: - normal - pending - firing - no_data - error toStatus: type: string enum: - normal - pending - firing - no_data - error fromSeverity: type: string enum: - info - warning - critical description: The severity band before this transition, absent when none matched. toSeverity: type: string enum: - info - warning - critical description: > The severity band after this transition, absent when none matched. A transition that changes only the level and not the status is still recorded, which is what lets the history show band flapping the inbox never saw. value: type: number format: double thresholdValue: type: number format: double reason: type: string enum: - breach - breach_cleared - for_satisfied - escalation - de_escalation - recovery - no_data - data_returned - error - too_many_instances - rule_changed - division_by_zero - guard_not_met - dimension_not_available - series_not_available - outside_evaluation_hours description: > The machine code for why this transition happened. recovery marks a firing instance going quiet and only that, so a pending instance that stops breaching is breach_cleared rather than a recovery that never fired. A transition into no_data carries the instance's noDataReason here instead, so why there was no value survives from the computation into the history - which is why the values from too_many_instances on overlap that vocabulary. outside_evaluation_hours marks a pending instance returning to normal because its evaluation hours ended. message: type: string notified: type: boolean evaluatedMs: type: integer format: int64 createdMs: type: integer format: int64 observeAlertNotification: type: object required: - id - alertRuleID - alertInstanceID - transition - channel - target - status - createdMs - updatedMs properties: id: type: string description: Alert notification ID (format `ano-`). alertRuleID: type: string description: Alert rule ID (format `aru-`). alertInstanceID: type: string description: Alert instance ID (format `ain-`). labels: type: object additionalProperties: type: string description: > The label set of the alert instance this row is about, resolved from alertInstanceID so the history can name the alert the way the alert list does. Absent for the ungrouped alert of a rule with no groupBy, which has no labels. transition: type: string enum: - firing - resolved - no_data - error channel: type: string enum: - email - webhook - pagerduty target: type: string description: >- Where this delivery went - an email address, the scheme and host of a webhook URL, or the PagerDuty events endpoint. dedupeKey: type: string firingID: type: string description: >- The transition this notification was sent for (format `atr-`), for `GET /observe/alertFirings/{alertFiringID}`. Absent for notifications sent before it was recorded. errorMessage: type: string sentMs: type: integer format: int64 status: type: string enum: - pending - sent - failed createdMs: type: integer format: int64 updatedMs: type: integer format: int64 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 observeAlertValueFormat: type: object description: >- How the values and thresholds of a rule type are written for people. Values and thresholds stay raw numbers in every response; apply this to display them. required: - unit - decimals - suffix properties: unit: type: string enum: - percent - count description: What the values measure. decimals: type: integer minimum: 0 description: >- Exact number of decimal places to show. Trailing zeros are kept, so values line up. suffix: type: string description: >- Text to append after the number, for example `%`. Empty when the unit needs none. observeAlertVocabulary: type: object description: > What the numbers and settings of a rule type are called, so every place that shows them names them the same way. A type with variants names them by the variant a rule picks ("Logins counted"), with the same term keys for every variant. What depends on other settings or on one evaluation, such as the length of the window, is not part of a term. required: - value - measures - minimum - gateMeasure - settings properties: value: $ref: '#/components/schemas/observeAlertTerm' description: >- The number thresholds are compared with, for example "% of expected". measures: type: array maxItems: 20 description: > The counts each evaluation stores in its details and computes the value from, measured count first. items: $ref: '#/components/schemas/observeAlertMeasure' minimum: $ref: '#/components/schemas/observeAlertMeasure' description: >- The sample gate each evaluation stores. Below it an alert is not judged. gateMeasure: type: string description: The key of the measure the minimum is checked against. settings: type: array maxItems: 20 description: >- The settings sentences about the numbers name, keyed by the setting's field in the rule config. items: $ref: '#/components/schemas/observeAlertTerm' observeAlertTerm: type: object description: >- One word customer-facing text uses. The key is stable, the name is the label, the help is one sentence. required: - key - name - help properties: key: type: string name: type: string help: type: string observeAlertMeasure: type: object description: > A term for a number an evaluation stores in its details, under detailKey. Use detailKey to request it from the alert instance statistics. required: - key - name - help - detailKey - reference properties: key: type: string name: type: string help: type: string detailKey: type: string reference: type: boolean description: Whether this is what the measured count is compared with. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.