> ## 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 instance series

> Returns the evaluations of several alert instances over one window, rolled up into buckets, for an
overview that charts many alerts at once. The bucket size follows the window: 5 minutes for a window
of up to 2 days, an hour for a longer one; `bucketSeconds` in the response says which. Each bucket
carries the instance's value (min, avg, max), threshold and status counts, and the evaluation details
fields its rule type charts (the counts behind the value and, for a forecast rule, the forecasted
range and forecast). Only evaluated buckets are returned. Instances that do not exist or belong to
another project are left out rather than reported as an error. Evaluations have shorter retention
than the instances themselves; expired history comes back empty.

Required API key permission: `observe:alerts:read`.



## OpenAPI

````yaml /api-reference/openapi/observe.yaml get /observe/alertInstanceSeries
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: ObservePasskeyIntelligence
    description: Passkey login predictions and support diagnosis
    x-group: Passkey Intelligence
  - 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: ObserveErrorModel
    description: >-
      The Observe error model, imported as one bundle file per version (Corbado
      internal)
  - 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: ObserveSavedFilter
    description: >-
      Saved filters, named flow filters a project stores once and applies by
      reference
    x-group: Saved filters
  - 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
  - name: ObserveSri
    description: Subresource Integrity hashes of the scripts Corbado hosts for a project
  - name: ObserveAutocapture
    description: >-
      Autocapture builds, candidates and releases, registered by Corbado's
      delivery pipeline
  - name: ObserveNotification
    description: >-
      Who is notified about what happens in a project, e.g. autocapture
      releases, and how it was delivered
  - name: ObservePasskey
    x-group: Passkey analysis
    description: Observed passkey search and cohort analysis.
paths:
  /observe/alertInstanceSeries:
    get:
      tags:
        - ObserveAlert
      summary: List alert instance series
      description: >-
        Returns the evaluations of several alert instances over one window,
        rolled up into buckets, for an

        overview that charts many alerts at once. The bucket size follows the
        window: 5 minutes for a window

        of up to 2 days, an hour for a longer one; `bucketSeconds` in the
        response says which. Each bucket

        carries the instance's value (min, avg, max), threshold and status
        counts, and the evaluation details

        fields its rule type charts (the counts behind the value and, for a
        forecast rule, the forecasted

        range and forecast). Only evaluated buckets are returned. Instances that
        do not exist or belong to

        another project are left out rather than reported as an error.
        Evaluations have shorter retention

        than the instances themselves; expired history comes back empty.


        Required API key permission: `observe:alerts:read`.
      operationId: ObserveAlertInstanceSeriesList
      parameters:
        - name: alertInstanceIDs
          in: query
          required: true
          description: >-
            The alert instances to return, comma-separated (format
            `ain-<number>`, at most 40).
          style: form
          explode: false
          schema:
            type: array
            minItems: 1
            maxItems: 40
            items:
              type: string
          x-oapi-codegen-extra-tags:
            validate: required,min=1,max=40,unique,dive,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 31 days.
          schema:
            type: integer
            format: int64
          x-oapi-codegen-extra-tags:
            validate: required
      responses:
        '200':
          description: The series of the requested alert instances.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/observeAlertInstanceSeriesList'
        default:
          $ref: '#/components/responses/error'
      security:
        - bearerAuth:
            - observe:alerts:read
components:
  schemas:
    observeAlertInstanceSeriesList:
      type: object
      required:
        - bucketSeconds
        - items
      properties:
        bucketSeconds:
          type: integer
          description: Length of every bucket in seconds (300 or 3600).
        items:
          type: array
          maxItems: 40
          description: >-
            One entry per requested instance that exists, in the order
            requested.
          items:
            $ref: '#/components/schemas/observeAlertInstanceSeries'
    observeAlertInstanceSeries:
      type: object
      required:
        - alertInstanceID
        - buckets
      properties:
        alertInstanceID:
          type: string
          description: The alert instance (format `ain-<number>`).
        buckets:
          type: array
          description: The instance's evaluated buckets in the window, oldest first.
          items:
            $ref: '#/components/schemas/observeAlertEvaluationBucket'
    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
    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. Evaluations outside the
        alert's evaluation hours have no value and are counted in
        outsideHoursCount only, not in the per-status counts.
      required:
        - bucketStartMs
        - evaluationCount
        - normalCount
        - pendingCount
        - firingCount
        - noDataCount
        - errorCount
        - outsideHoursCount
      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.
        windowSeconds:
          type: number
          format: double
          description: >
            The average length in seconds of the windows this hour's evaluations
            read. Each details field is a count over one such window, so
            dividing by it turns the field into a rate.
        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
        outsideHoursCount:
          type: integer
          description: >
            Evaluations in this hour outside the alert's evaluation hours. The
            alert was not judged then - it kept its status and has no value - so
            these are not in the per-status counts.
        details:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/observeAlertEvaluationBucketDetail'
          description: >
            The requested evaluation details fields aggregated over this hour,
            keyed by field. A field is absent from an hour in which no
            evaluation had it. Absent when no fields were requested.
    observeAlertEvaluationBucketDetail:
      type: object
      description: >
        One evaluation details field over one hour's evaluations. Each
        evaluation reads a whole window and consecutive windows overlap, so the
        field is averaged rather than summed.
      required:
        - min
        - avg
        - max
      properties:
        min:
          type: number
          format: double
        avg:
          type: number
          format: double
        max:
          type: number
          format: double
  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.