> ## 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. # Simulate alert rule > Evaluates an alert rule config over the last seven days and reports how often it would have fired, per group and per hour. The rule does not need to be saved. Nothing is stored as an alert, and nobody is notified. What is simulated: the rule exactly as sent, evaluated every `stepMs` (as often as live evaluation runs) with the same evaluation live rules use: the value per group from the window and baseline, the conditions, the pending period (`for`), recovery, the no data policy, `minExpected`, evaluation hours and overrides. Each evaluation continues from the alerts the previous one left, so an alert that fired stays firing until it recovers, as live. Input data: the flows or subflows the rule counts, as they are stored now, in one-minute buckets. Each evaluation reads the window ending `dataDelayMs` before it, a fixed delay per rule type; delays from processing backlogs at that time are not known any more and are not simulated. Flows classified late are included, so a simulation can see slightly more than the live evaluation saw at the time. Not simulated: notifications. The contact point, its integrations and its delivery hours are not taken into account; the result says when alerts would have fired, not who would have been notified when. The first simulation reads the data the rule needs, which can take a minute; the response streams its progress as `application/x-ndjson` and ends with a `completed` event carrying the result, or a `failed` event. Send the `toMs` of that result with every later simulation of the same rule: as long as the rule's type, flow or subflow type and grouping stay the same, the data is reused and the simulation answers in about a second, so thresholds, windows and pending periods can be tuned freely. Validation errors return a regular JSON error before streaming starts. Only `flow_volume` and `subflow_volume` rules can be simulated. Required API key permission: `observe:alerts:read`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml post /observe/alertRules/simulate 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: 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/alertRules/simulate: post: tags: - ObserveAlert summary: Simulate alert rule description: >- Evaluates an alert rule config over the last seven days and reports how often it would have fired, per group and per hour. The rule does not need to be saved. Nothing is stored as an alert, and nobody is notified. What is simulated: the rule exactly as sent, evaluated every `stepMs` (as often as live evaluation runs) with the same evaluation live rules use: the value per group from the window and baseline, the conditions, the pending period (`for`), recovery, the no data policy, `minExpected`, evaluation hours and overrides. Each evaluation continues from the alerts the previous one left, so an alert that fired stays firing until it recovers, as live. Input data: the flows or subflows the rule counts, as they are stored now, in one-minute buckets. Each evaluation reads the window ending `dataDelayMs` before it, a fixed delay per rule type; delays from processing backlogs at that time are not known any more and are not simulated. Flows classified late are included, so a simulation can see slightly more than the live evaluation saw at the time. Not simulated: notifications. The contact point, its integrations and its delivery hours are not taken into account; the result says when alerts would have fired, not who would have been notified when. The first simulation reads the data the rule needs, which can take a minute; the response streams its progress as `application/x-ndjson` and ends with a `completed` event carrying the result, or a `failed` event. Send the `toMs` of that result with every later simulation of the same rule: as long as the rule's type, flow or subflow type and grouping stay the same, the data is reused and the simulation answers in about a second, so thresholds, windows and pending periods can be tuned freely. Validation errors return a regular JSON error before streaming starts. Only `flow_volume` and `subflow_volume` rules can be simulated. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertRuleSimulate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observeAlertRuleSimulateReq' responses: '200': description: >- Newline-delimited JSON progress stream; the final line carries the simulation result. content: application/x-ndjson: schema: $ref: '#/components/schemas/observeAlertRuleSimulationEvent' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:alerts:read components: schemas: observeAlertRuleSimulateReq: type: object required: - ruleType - rule properties: ruleType: type: string enum: - login_success_rate - flow_volume - subflow_volume description: Type of the rule to simulate. x-oapi-codegen-extra-tags: validate: required,oneof=login_success_rate flow_volume subflow_volume rule: $ref: '#/components/schemas/observeAlertRuleConfig' toMs: type: integer format: int64 description: >- End of the simulated range in milliseconds since epoch, from the `toMs` of an earlier simulation of the same rule. Omit it to simulate the seven days up to now. It must have ended within the last 24 hours. focus: type: object additionalProperties: type: string description: >- Labels of one group, e.g. `{"country": "DE"}`, whose every step the result carries for a detailed chart. An ungrouped rule's only group has no labels: send `{}`. observeAlertRuleSimulationEvent: type: object description: One line of a simulation's progress stream. required: - type properties: type: type: string enum: - started - progress - completed - failed description: >- `started` comes first, `progress` after every chunk of data read (repeated while a chunk takes long), and either `completed` with the result or `failed` last. chunksDone: type: integer description: Chunks of data read so far (progress events). chunksTotal: type: integer description: Chunks of data to read in total (progress events). simulation: $ref: '#/components/schemas/observeAlertRuleSimulation' message: type: string description: Why the simulation failed (failed events). observeAlertRuleConfig: type: object description: > The configuration of an alert rule: the generic envelope every rule type shares, plus one settings object belonging to the rule type named by type. Everything outside settings is implemented once, generically - the window is resolved and handed to the rule type as two absolute timestamps, and the conditions are applied to whatever number the rule type returned, so a rule type never sees the thresholds. Shape and vocabulary are validated here. The semantics that span fields - that the bands get stricter as the level does, that recovery sits on the lenient side of them, that the window is a whole number of days, and that groupBy names dimensions this project actually has - are validated when the rule is saved and again when it is evaluated, because only the second catches a project that changed after the rule was written. required: - version - type - window - conditions properties: version: type: integer minimum: 1 maximum: 1 description: >- Config schema version. Only 1 exists; a stored rule carries it so a later shape change can be migrated rather than guessed at. x-oapi-codegen-extra-tags: validate: required,oneof=1 type: type: string enum: - login_success_rate - flow_volume - subflow_volume description: > The rule type this config belongs to. Must equal the rule's ruleType - the two are stored separately and the evaluator reads the column to pick the implementation, so letting them disagree would store a rule whose settings belong to one type and whose evaluation belongs to another. x-oapi-codegen-extra-tags: validate: required,oneof=login_success_rate flow_volume subflow_volume window: type: string description: > How much history the value covers - "5m", "1h", "3d". Go duration syntax extended with "d" and "w". A rule type that reads pre-aggregated buckets needs a whole number of them: login_success_rate reads an hourly series, so its window must be whole hours; flow_volume and subflow_volume take one of their offered windows (1m to 1h) and slide with the evaluation instant. The window ends a type-specific delay behind the evaluation instant, so the data it covers has arrived; that delay is not configurable. x-oapi-codegen-extra-tags: validate: required groupBy: type: array maxItems: 10 description: > Dimension keys to alert separately by: one alert instance per combination of values, each with its own state and its own for clock. Keys are dimension names as reported by the rule type for this project, never columns or tag slots - a project that reorders its tags must not silently regroup a rule onto whatever now sits in that position. Empty means one ungrouped instance. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,unique,dive,required maxInstances: type: integer minimum: 1 maximum: 500 description: >- Cardinality cap for a grouped rule. Exceeding it is an error rather than a truncation, so a rule cannot quietly stop covering part of its groups. Defaults to 50. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500 settings: type: object additionalProperties: true description: > Settings belonging to type, opaque to the envelope. For login_success_rate this is observeAlertRuleSettingsLoginSuccessRate, for flow_volume observeAlertRuleSettingsFlowVolume, for subflow_volume observeAlertRuleSettingsSubflowVolume. This field stays open rather than a union, so a rule type can be added without a breaking change to this schema. conditions: type: array minItems: 1 maxItems: 3 description: > The severity bands, most severe matching band wins. All conditions must compare in the same direction, each level may appear at most once, and a more severe band must breach later than a less severe one. An equality band stands alone. There is no rule-level severity; each condition carries its own level. items: $ref: '#/components/schemas/observeAlertRuleCondition' x-oapi-codegen-extra-tags: validate: required,min=1,max=3,dive recovery: $ref: '#/components/schemas/observeAlertRuleRecovery' for: type: string description: > How long a group must stay breached before it fires, measured per instance from its own first breach - e.g. "1d". Omit to fire on the first breaching evaluation. noData: type: string enum: - ok - no_data - alerting - keep_last description: > What an instance does when its group produces no value. Defaults to no_data, which is visible in the panel and sends nothing - where keep_last would hold a firing alert firing forever and ok would quietly resolve one. x-oapi-codegen-extra-tags: validate: omitempty,oneof=ok no_data alerting keep_last evaluationHours: $ref: '#/components/schemas/observeAlertHours' overrides: type: array description: > Exceptions to the rule for particular alerts. An override's match is a complete label set - one value for every groupBy key - and it applies to exactly the alert with that label set. The alert is judged by the override's values instead of the rule's, field by field: a field the override sets replaces the rule's wholesale, a field it leaves out is inherited. Editing overrides never touches an alert's identity or history - the new values simply apply at the next evaluation. Requires groupBy; no cap on the count. items: $ref: '#/components/schemas/observeAlertRuleOverride' x-oapi-codegen-extra-tags: validate: omitempty,dive observeAlertRuleSimulation: type: object required: - cached - fromMs - toMs - stepMs - dataDelayMs - fired - firedBySeverity - maxGroups - failedSteps - groups properties: cached: type: boolean description: >- Whether the data came from an earlier simulation instead of a new read. fromMs: type: integer format: int64 description: Start of the simulated range, in milliseconds since epoch. toMs: type: integer format: int64 description: >- End of the simulated range, in milliseconds since epoch. Send it as `toMs` with the next simulation of this rule. stepMs: type: integer format: int64 description: How often the rule is evaluated, as live. dataDelayMs: type: integer format: int64 description: How far behind each evaluation its window ends. fired: type: integer description: >- How many times an alert fired: it started firing, or escalated to a severity above any before in its episode. These are the two events live evaluation notifies about. firedBySeverity: $ref: '#/components/schemas/observeAlertRuleSimulationSeverityCounts' maxGroups: type: integer description: >- The most groups a single evaluation produced, to compare with the rule's maxInstances. failedSteps: type: integer description: >- Evaluations that failed as a whole, because the rule produced more groups than its maxInstances. error: $ref: '#/components/schemas/observeAlertRuleSimulationError' groups: type: array description: Every group the rule evaluated, most alerts first. items: $ref: '#/components/schemas/observeAlertRuleSimulationGroup' focus: $ref: '#/components/schemas/observeAlertRuleSimulationFocus' 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 observeAlertRuleCondition: type: object description: >- One severity band - a comparison against a threshold that yields a level. required: - severity - operator - threshold properties: severity: type: string enum: - info - warning - critical description: >- The severity this band produces. It belongs to the condition rather than to the rule, so an alert may fire at warning and escalate to critical without changing identity. x-oapi-codegen-extra-tags: validate: required,oneof=info warning critical operator: type: string enum: - above - above_or_equal - below - below_or_equal - equal - not_equal description: How the rule's value is compared against threshold. x-oapi-codegen-extra-tags: validate: >- required,oneof=above above_or_equal below below_or_equal equal not_equal threshold: type: number format: double description: >- The value the band compares against. Zero is a meaningful threshold, so this field carries no required-value validation of its own. observeAlertRuleRecovery: type: object description: > An optional separate threshold a firing instance must clear before it resolves. Without one a rule can fire and resolve at the same value, which is the flapping this exists to prevent, so it must compare in the opposite direction to the conditions and sit on the lenient side of the least severe band. required: - operator - threshold properties: operator: type: string enum: - above - above_or_equal - below - below_or_equal - equal - not_equal x-oapi-codegen-extra-tags: validate: >- required,oneof=above above_or_equal below below_or_equal equal not_equal threshold: type: number format: double observeAlertHours: type: object description: > A weekly schedule, used in two places. It is read in the project's timezone, looked up each time the schedule is checked, so changing the project's timezone moves the schedule along. Only an override's evaluationHours may set a timezone of their own. As a contact point's deliveryHours it is when the contact point's integrations may deliver. A notification that falls outside these hours is not sent, and not sent later either; the alert's state is recorded all the same. Omit on create to deliver at any time, omit on update to keep the current hours. As a rule's evaluationHours it is when the rule's alerts are evaluated at all. Outside these hours an alert gets no value, with noDataReason outside_evaluation_hours, and the no-data policy does not apply: a firing alert stays firing, a pending alert returns to normal so its for period starts again, and nothing is notified. Set on an override, it replaces the rule's hours for that alert and may set a timezone, e.g. Australia/Sydney for an alert on Australia; mode always evaluates that alert at any time. Omit to evaluate at any time (on an override: to inherit the rule's hours). required: - mode properties: mode: type: string enum: - always - scheduled x-enum-varnames: - ObserveAlertHoursModeAlways - ObserveAlertHoursModeScheduled x-oapi-codegen-extra-tags: validate: required,oneof=always scheduled description: >- always is open at any time and takes no timezone or ranges; scheduled is open only inside ranges. timezone: type: string description: > IANA timezone the ranges are read in, e.g. Australia/Sydney. Only on an override's evaluationHours, and optional there; omit it to use the project's timezone. Delivery hours and a rule's own evaluationHours always use the project's timezone and reject this field. x-oapi-codegen-extra-tags: validate: omitempty,max=64 ranges: type: array maxItems: 10 description: Required when mode is scheduled. items: $ref: '#/components/schemas/observeAlertHoursRange' x-oapi-codegen-extra-tags: validate: omitempty,max=10,dive observeAlertRuleOverride: type: object description: > One exception to a rule: an alert's label set and a sparse patch of the per-alert fields. Only fields the evaluator and the rule type apply per alert can be set here - what shapes the read (window, groupBy, maxInstances) is one value per rule. required: - match properties: match: type: object additionalProperties: type: string description: > The alert's label set: one exact value for every one of the rule's groupBy keys, no more and no fewer. An override applies to exactly the alert carrying this label set. Two overrides with the same match are rejected. conditions: type: array minItems: 1 maxItems: 3 description: > The complete band set for matching alerts, validated by the same rules as the rule's own conditions and against the recovery threshold that applies (this override's, or the rule's when inherited). Omit to inherit the rule's bands. items: $ref: '#/components/schemas/observeAlertRuleCondition' x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=3,dive recovery: $ref: '#/components/schemas/observeAlertRuleRecovery' for: type: string description: >- Pending period for matching alerts, e.g. "3h". "0s" is a value - fire on the first breaching evaluation - and omitting it inherits the rule's. noData: type: string enum: - ok - no_data - alerting - keep_last description: No-data policy for matching alerts. Omit to inherit the rule's. x-oapi-codegen-extra-tags: validate: omitempty,oneof=ok no_data alerting keep_last settings: type: object additionalProperties: true description: > The complete settings object of the rule type for matching alerts - for login_success_rate, observeAlertRuleSettingsLoginSuccessRate. Replaces the rule's settings wholesale rather than merging into them. Omit to inherit the rule's. For flow_volume and subflow_volume an override may only set minExpected; the other settings shape the one read a rule makes. evaluationHours: $ref: '#/components/schemas/observeAlertHours' observeAlertRuleSimulationSeverityCounts: type: object description: How many times an alert fired, per severity it fired with. required: - info - warning - critical properties: info: type: integer warning: type: integer critical: type: integer observeAlertRuleSimulationError: type: object description: The first evaluation that failed as a whole. required: - atMs - reason - message properties: atMs: type: integer format: int64 reason: type: string message: type: string observeAlertRuleSimulationGroup: type: object required: - labels - fired - firedBySeverity - firingSteps - pendingSteps - noDataSteps - firedPerHour - firedPerHourBySeverity properties: labels: type: object additionalProperties: type: string description: The group's labels; empty for an ungrouped rule. fired: type: integer description: >- How many times the group's alert fired, as `fired` of the simulation. firedBySeverity: $ref: '#/components/schemas/observeAlertRuleSimulationSeverityCounts' firingSteps: type: integer description: Evaluations the alert was firing. pendingSteps: type: integer description: Evaluations the alert was pending. noDataSteps: type: integer description: >- Evaluations the alert had no data, including too few expected to judge. firedPerHour: type: array description: >- How many times the alert fired per hour of the simulated range, oldest hour first. items: type: integer firedPerHourBySeverity: $ref: '#/components/schemas/observeAlertRuleSimulationSeverityHours' lowestValue: type: number format: double description: The lowest value the group had. lowestValueAtMs: type: integer format: int64 description: When the group had its lowest value. observeAlertRuleSimulationFocus: type: object description: >- Every evaluation of the requested group, as parallel arrays with one entry per step from `fromMs` on, and the group's status changes. required: - labels - values - samples - statuses - noDataReasons - transitions properties: labels: type: object additionalProperties: type: string values: type: array description: The value per step; null where there was none. items: type: - number - 'null' format: double samples: type: array description: >- What the rule's sample gate (`minExpected` or `minSample`) judged per step: how many flows the value rests on. A step with fewer than the gate has no value. Null where nothing was read, e.g. outside the evaluation hours. items: type: - number - 'null' format: double statuses: type: array description: >- The status per step (normal, pending, firing, no_data or error); null before the group first appeared. items: type: - string - 'null' noDataReasons: type: array description: Why a step had no value; null where it had one. items: type: - string - 'null' transitions: type: array items: $ref: '#/components/schemas/observeAlertRuleSimulationTransition' observeAlertHoursRange: type: object description: > One block of time within a day, on some weekdays. start is before end; end is exclusive and may be 24:00, so a whole day is 00:00-24:00. Times are on a 15-minute step. required: - weekdays - start - end properties: weekdays: type: array minItems: 1 maxItems: 7 items: type: string enum: - mon - tue - wed - thu - fri - sat - sun x-enum-varnames: - ObserveAlertHoursRangeWeekdaysMon - ObserveAlertHoursRangeWeekdaysTue - ObserveAlertHoursRangeWeekdaysWed - ObserveAlertHoursRangeWeekdaysThu - ObserveAlertHoursRangeWeekdaysFri - ObserveAlertHoursRangeWeekdaysSat - ObserveAlertHoursRangeWeekdaysSun x-oapi-codegen-extra-tags: validate: required,min=1,max=7,dive,oneof=mon tue wed thu fri sat sun start: type: string description: Start time, HH:MM. example: '09:00' x-oapi-codegen-extra-tags: validate: required,min=5,max=5 end: type: string description: End time, HH:MM, exclusive. 24:00 runs to the end of the day. example: '18:00' x-oapi-codegen-extra-tags: validate: required,min=5,max=5 observeAlertRuleSimulationSeverityHours: type: object description: >- How many times the alert fired per hour of the simulated range and severity, oldest hour first. required: - info - warning - critical properties: info: type: array items: type: integer warning: type: array items: type: integer critical: type: array items: type: integer observeAlertRuleSimulationTransition: type: object required: - atMs - toStatus - reason properties: atMs: type: integer format: int64 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 toSeverity: type: string enum: - info - warning - critical value: type: number format: double reason: type: string 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.