> ## 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 instance statistics > Returns an alert instance's hourly evaluation aggregates and status timeline with per-status totals. Only evaluated hours have buckets. The timeline starts with the status held at `fromMs`, using the last preceding transition. Evaluations have shorter retention than transitions; expired history returns empty results rather than an error. Required API key permission: `observe:alerts:read`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml get /observe/alertInstanceStatistics 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/alertInstanceStatistics: get: tags: - ObserveAlert summary: Get alert instance statistics description: >- Returns an alert instance's hourly evaluation aggregates and status timeline with per-status totals. Only evaluated hours have buckets. The timeline starts with the status held at `fromMs`, using the last preceding transition. Evaluations have shorter retention than transitions; expired history returns empty results rather than an error. Required API key permission: `observe:alerts:read`. operationId: ObserveAlertInstanceStatisticsGet parameters: - name: alertInstanceID in: query required: true description: The alert instance to describe (format `ain-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=ain - name: fromMs in: query required: true description: Window start (epoch ms, inclusive). schema: type: integer format: int64 x-oapi-codegen-extra-tags: validate: required - name: toMs in: query required: true description: >- Window end (epoch ms, exclusive). Must be after fromMs; the window may span at most 366 days. schema: type: integer format: int64 x-oapi-codegen-extra-tags: validate: required responses: '200': description: Statistics for the alert instance over the window. content: application/json: schema: $ref: '#/components/schemas/observeAlertInstanceStatistics' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:alerts:read components: schemas: observeAlertInstanceStatistics: type: object description: > One alert instance's history over a requested window, in the two shapes the statistics panel draws: an hourly-bucketed evaluation series for the value chart, and the status timeline as merged phases plus per-status totals. The series carries only the hours that have evaluations; the phases jointly cover the window from the first known status to the earlier of the window's end and now. required: - series - phases - totals properties: series: type: array maxItems: 2500 items: $ref: '#/components/schemas/observeAlertEvaluationBucket' phases: type: array maxItems: 10000 items: $ref: '#/components/schemas/observeAlertStatusPhase' totals: $ref: '#/components/schemas/observeAlertStatusTotals' thresholdValue: type: number format: double description: >- The instance's current threshold, for the chart's reference line. Absent when no band applies. observeAlertEvaluationBucket: type: object description: > One hour of an instance's evaluations, aggregated. min/avg/max are computed over the evaluations that produced a value; an hour whose evaluations were all no_data carries counts but no values, which is a different statement from zero and the true one. required: - bucketStartMs - evaluationCount - normalCount - pendingCount - firingCount - noDataCount - errorCount properties: bucketStartMs: type: integer format: int64 description: >- Start of the hour bucket, in milliseconds since epoch (UTC hour boundaries). minValue: type: number format: double avgValue: type: number format: double maxValue: type: number format: double thresholdValue: type: number format: double description: >- The threshold in effect during this hour - the largest one, if it changed mid-hour. evaluationCount: type: integer description: Every evaluation in this hour, whatever its status. normalCount: type: integer pendingCount: type: integer firingCount: type: integer noDataCount: type: integer errorCount: type: integer observeAlertStatusPhase: type: object description: > One contiguous stretch of the timeline in a single status. Phases are merged - a severity-only transition does not split one - and clamped to the requested window, so they abut without gaps from the first known status to the earlier of the window's end and now. required: - fromMs - toMs - status properties: fromMs: type: integer format: int64 toMs: type: integer format: int64 status: type: string enum: - normal - pending - firing - no_data - error severity: type: string enum: - info - warning - critical description: The severity band when the phase began, absent when none matched. observeAlertStatusTotals: type: object description: > How long the instance spent in each status within the window, and how often it fired. Every field is present, zero included, and the durations add up to the covered part of the window - the stretch before the instance existed, or after now, is in none of them. required: - normalMs - pendingMs - firingMs - noDataMs - errorMs - firingCount properties: normalMs: type: integer format: int64 pendingMs: type: integer format: int64 firingMs: type: integer format: int64 noDataMs: type: integer format: int64 errorMs: type: integer format: int64 firingCount: type: integer description: How many separate firing phases the window contains. 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. ````