> ## 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.

# Calculate historical metrics for an exact journey position

> Required API key permission: `observe:timeSeries:read`.



## OpenAPI

````yaml /api-reference/openapi/observe.yaml post /observe/funnel/metricSeries
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/funnel/metricSeries:
    post:
      tags:
        - ObserveFunnel
      summary: Calculate historical metrics for an exact journey position
      description: 'Required API key permission: `observe:timeSeries:read`.'
      operationId: ObserveFunnelMetricSeriesGet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObserveFunnelHistoryMetricSeriesRequest'
      responses:
        '200':
          description: Daily or hourly metrics, including empty buckets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObserveFunnelHistoryMetricSeriesResponse'
        '400':
          description: Invalid selection, filters, metrics or range
        '429':
          description: Shared history calculation capacity is busy
      security:
        - bearerAuth:
            - observe:timeSeries:read
components:
  schemas:
    ObserveFunnelHistoryMetricSeriesRequest:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - name
        - fromDate
        - toDate
        - interval
        - metrics
      properties:
        schemaVersion:
          type: string
          enum:
            - funnel-metric-v1
        name:
          type: string
          enum:
            - login-flow-v1
            - signup-flow-v1
            - recovery-flow-v1
            - security-enrollment-flow-v1
        fromDate:
          type: string
          description: >-
            Inclusive UTC-naive datetime, YYYY-MM-DDTHH:mm:ss; aligned to
            project bucket boundaries
        toDate:
          type: string
          description: >-
            Exclusive end of the requested range, in UTC without a timezone
            suffix. Must be later than

            fromDate. History without a comparison can cover at most 180
            project-local calendar days.

            With a comparison, each period can cover at most 90 calendar days
            and the full range can cover

            at most 181 days, including any gap. The extra day allows two 90-day
            periods to keep matching

            weekdays when the baseline starts 91 days earlier.
        interval:
          type: string
          enum:
            - daily
            - hourly
        selection:
          allOf:
            - $ref: '#/components/schemas/ObserveFunnelHistorySelection'
          description: >-
            Required for single-position bucket history. Mutually exclusive with
            selections. Omission requires selections with output totals, or
            output positions (selections optional there).
        output:
          type: string
          enum:
            - buckets
            - totals
            - positions
          default: buckets
          description: >-
            Use buckets to follow one selected position over time, with optional
            cohort breakdowns and period

            comparison. Use totals to get counts and rates for several selected
            positions without time buckets,

            comparisons or breakdowns. Use positions to compare two periods
            across selected positions and find

            additional routes whose traffic increased, decreased or began or
            ended partway through a period.

            Positions requires daily intervals and two comparison periods,
            accepts no breakdowns and returns the

            overall funnel comparison in root and individual results in
            positions.
        selections:
          type: array
          minItems: 1
          maxItems: 1000
          description: >-
            Positions to compare or total together. Use with totals or positions
            output, without selection.

            With totals, non-root results appear in nodes and the root remains
            the top-level result.

            With positions, requested results appear in positions alongside any
            additional discovered routes.

            Requested positions are included even when they have no traffic.
          items:
            $ref: '#/components/schemas/ObserveFunnelHistorySelection'
        comparison:
          $ref: '#/components/schemas/ObserveFunnelHistoryComparison'
        discovery:
          $ref: '#/components/schemas/ObserveFunnelHistoryDiscovery'
        filters:
          $ref: '#/components/schemas/ObserveFunnelHistoryFilters'
        breakdowns:
          type: array
          minItems: 1
          maxItems: 30
          description: >-
            Compare cohorts at the selected position, such as browsers or
            applications. Each dimension is a

            separate breakdown of the same filtered traffic and may appear only
            once. Omit values to include

            the groups observed in the requested range. Results from different
            dimensions can overlap and

            should not be added together. The total number of group values
            across dimensions, multiplied by

            the number of time buckets, must not exceed 100000.
          items:
            $ref: '#/components/schemas/ObserveFunnelHistoryBreakdown'
        metrics:
          type: array
          minItems: 1
          maxItems: 19
          items:
            type: string
            enum:
              - flowsReached
              - attemptsReached
              - occurrences
              - eventualCompletionRate
              - attemptCompletionRate
              - flowErrorRate
              - retriedFlowRate
              - eventualCompletionTime
              - subflowCompletionRate
              - completedHereRate
              - dropoffRate
              - retryHereRate
              - continueRate
              - completedHereTime
              - stepErrorRate
              - edgeShare
              - eventualSkipRate
              - eventualDropoffRate
              - skippedHereRate
    ObserveFunnelHistoryMetricSeriesResponse:
      type: object
      required:
        - schemaVersion
        - projectID
        - name
        - timeZone
        - timeBasis
        - selection
        - buckets
        - totals
        - summary
        - coverage
      properties:
        nodes:
          type: array
          description: >-
            Present only for batched totals. Explicitly requested non-root
            node/edge positions in deterministic semantic-prefix order, each
            with empty buckets and no nested nodes. The top-level result is the
            root. Unparseable source rows conservatively invalidate all position
            metrics. No silent truncation.
          items:
            $ref: '#/components/schemas/ObserveFunnelHistoryMetricSeriesResponse'
        root:
          $ref: '#/components/schemas/ObserveFunnelHistoryPositionsRoot'
        positions:
          type: array
          description: >-
            Output positions only. Requested selections first (request order),
            then discovered non-stable positions by volume. Counts and summaries
            equal output totals for the same period and selection.
          items:
            $ref: '#/components/schemas/ObserveFunnelHistoryPosition'
        extrasTruncated:
          type: integer
          description: >-
            Output positions only. Discovered non-stable positions beyond
            discovery.maxExtra
        comparison:
          $ref: '#/components/schemas/ObserveFunnelHistoryComparisonResult'
        schemaVersion:
          type: string
        projectID:
          type: string
        name:
          type: string
        timeZone:
          type: string
        timeBasis:
          type: string
          enum:
            - flow-start
        selection:
          $ref: '#/components/schemas/ObserveFunnelHistorySelection'
        totals:
          $ref: '#/components/schemas/ObserveFunnelHistoryCounts'
        summary:
          type: object
          description: >-
            Full-period metrics calculated from merged counts/histograms. All
            values are null when candidate paths could not be interpreted.
            Counts and totals then cover decoded records only.
          additionalProperties:
            $ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'
        breakdowns:
          type: array
          maxItems: 30
          description: >-
            Independent results for a breakdowns request, in request order. An
            empty groups array means no values passed the requested support
            screen. Omit breakdowns for baseline metrics only.
          items:
            $ref: '#/components/schemas/ObserveFunnelHistoryBreakdownResult'
        unavailableMetrics:
          type: object
          description: >-
            Reasons for unavailable or inapplicable metrics; corresponding
            values are null
          additionalProperties:
            type: string
        buckets:
          type: array
          items:
            type: object
            properties:
              time:
                type: string
                format: date-time
              counts:
                $ref: '#/components/schemas/ObserveFunnelHistoryCounts'
              unparsedRows:
                type: integer
                format: int64
                description: Nonzero makes every metric in this bucket unavailable
              unparsedWeight:
                type: number
                format: double
                description: Candidate flow weight that could not be interpreted
              values:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'
        coverage:
          type: object
          properties:
            firstBucket:
              type: string
              format: date-time
            endExclusive:
              type: string
              format: date-time
            snapshotDate:
              type: string
              format: date
            completeWindow:
              type: boolean
              description: >-
                Bounds lie within recorded coverage; not a completeness
                guarantee for every interior bucket
            notes:
              type: array
              items:
                type: string
        diagnostics:
          type: object
          description: >-
            Calculation timings and processed-cell counts. Shard timings overlap
            and must not be added as end-to-end latency.
          required:
            - rowsScanned
            - rowsMatched
            - rowsUnparsed
          properties:
            rowsScanned:
              type: integer
              format: int64
              description: Aggregated cells delivered by SQL after all WHERE predicates
            rowsMatched:
              type: integer
              format: int64
              description: Cells whose decoded path contributed to the selection
            rowsUnparsed:
              type: integer
              format: int64
              description: >-
                Aggregated cells that could not be decoded after a bounded
                dictionary refresh. Affected bucket metrics and whole-period
                summaries are unavailable; counts and totals describe decoded
                records only.
            weightUnparsed:
              type: number
              format: double
              description: >-
                Sum of undecodable candidate row weights, not a count of
                confirmed matches at this position.
          additionalProperties: true
    ObserveFunnelHistorySelection:
      type: object
      additionalProperties: false
      required:
        - kind
        - scope
        - prefix
      properties:
        kind:
          type: string
          enum:
            - node
            - edge
        scope:
          type: string
          enum:
            - prefix
            - anywhere
        prefix:
          type: array
          maxItems: 32
          description: >-
            Exact normalized attempt prefix including the target node (or edge
            source). Empty prefix selects the flow root. Anywhere requires
            exactly one step and counts a flow/attempt once even if it matches
            multiple positions.
          items:
            $ref: '#/components/schemas/ObserveFunnelHistoryStep'
        destination:
          allOf:
            - $ref: '#/components/schemas/ObserveFunnelHistoryStep'
          description: >-
            Required only for edges; immediate next structural step, not an
            eventual-reach condition or visually folded edge
    ObserveFunnelHistoryComparison:
      type: object
      additionalProperties: false
      required:
        - baseline
        - current
      description: >-
        Optional daily comparison. Both periods must be nonempty, contained
        within the request range, and baseline must end no later than current
        starts. Unequal lengths are supported. Periods do not change the daily
        chart or full-range totals.
      properties:
        baseline:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriod'
        current:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriod'
    ObserveFunnelHistoryDiscovery:
      type: object
      additionalProperties: false
      description: >-
        With positions output, include additional routes whose traffic changed,
        even when they are absent from the current funnel view.
      properties:
        maxExtra:
          type: integer
          minimum: 0
          maximum: 1000
          default: 200
          description: >-
            Maximum additional positions to return, with the busiest first.
            extrasTruncated reports

            how many qualifying positions were omitted.
        minFlows:
          type: number
          format: double
          minimum: 0
          default: 1000
          description: >-
            Minimum flow count per seven days for traffic classification, scaled
            to each period's length.
        maxDepth:
          type: integer
          minimum: 1
          description: >-
            Maximum number of steps from the start when finding additional
            positions. Also limits which

            positions can exclude flows from the like-for-like comparison.
            Requested positions are still

            evaluated in full.
    ObserveFunnelHistoryFilters:
      type: object
      additionalProperties: false
      description: >-
        Values within a dimension are ORed; dimensions are ANDed. Omitted
        filters mean all. Null includes rows where a supported dimension is
        absent or empty.
      properties:
        browserHierarchy:
          $ref: '#/components/schemas/ObserveFunnelHistoryBrowserHierarchyFilter'
        applicationIDs:
          type: array
          x-go-type: '[]*string'
          maxItems: 100
          description: >-
            Application IDs in `app-<number>` format, scoped to the
            authenticated project. Time-series panels expose

            the numeric portion as dimensions.applicationId; clients must prefix
            those string values with app- when

            building this filter. Values are ORed and applied before aggregation
            to buckets, totals, comparisons,

            breakdowns and batched selections. Omitted or empty means all
            applications; valid IDs without matching

            project data return zero counts. Null includes rows without an
            application ID.
          items:
            type:
              - string
              - 'null'
          example:
            - app-12345678910
        osNames:
          type: array
          items:
            type:
              - string
              - 'null'
          x-go-type: '[]*string'
        browserNames:
          type: array
          items:
            type:
              - string
              - 'null'
          x-go-type: '[]*string'
        osVersions:
          type: array
          items:
            type: string
        touchpoints:
          type: array
          items:
            type:
              - string
              - 'null'
          x-go-type: '[]*string'
        customTags:
          type: object
          x-go-type: map[string][]*string
          description: >-
            Physical slots customTag1..20; slot names resolved via project
            configuration. Null includes absent or empty values.
          additionalProperties:
            type: array
            items:
              type:
                - string
                - 'null'
        outcomes:
          type: array
          items:
            type: string
            enum:
              - complete
              - incomplete
              - skipped
              - invisible
              - visible-auto-skip
        engagement:
          type: string
          enum:
            - all
            - engaged
            - non-engaged
        attemptNumbers:
          type: array
          items:
            type: string
            enum:
              - '1'
              - '2'
              - '3'
              - 4+
    ObserveFunnelHistoryBreakdown:
      type: object
      additionalProperties: false
      required:
        - dimension
      description: >-
        Subsets of the already filtered population. The top-level baseline
        retains other and missing values. One scan calculates all requested
        groups. Box dimensions require a subflow target and return
        occurrence-based boxShare values; flow membership may overlap across
        retries. boxLeaf accepts one JSON-encoded selector with group and
        optional secondary field/value or authenticator exclusions, and returns
        focused occurrence metrics.
      properties:
        dimension:
          type: string
          enum:
            - os
            - browser
            - os-browser
            - device-browser
            - applicationID
            - customTag1
            - customTag2
            - customTag3
            - customTag4
            - customTag5
            - customTag6
            - customTag7
            - customTag8
            - customTag9
            - customTag10
            - customTag11
            - customTag12
            - customTag13
            - customTag14
            - customTag15
            - customTag16
            - customTag17
            - customTag18
            - customTag19
            - customTag20
            - boxOutcome
            - boxProvider
            - boxAutofillType
            - boxFieldName
            - boxLeaf
        omitEmpty:
          type: boolean
          default: false
          description: >-
            Omit groups with no target or source observations across the whole
            range. Does not remove low-volume groups.
        minWeeklyObservations:
          type: integer
          minimum: 0
          description: >-
            Optional daily-only traffic screen after merging. With comparison,
            uses completed calendar days in its two periods, scaled by completed
            days / 7. Without comparison, checks the first and last seven days.
            Zero disables it.
        values:
          description: >-
            In a breakdowns request, omit values to discover and return every
            observed nonempty value while calculating the selected population.
            Explicit lists restrict the returned groups. boxLeaf requires
            explicit values. All discovered groups share the 100000 group-bucket
            budget; exceeding it returns an error, never silent truncation.
          type: array
          minItems: 1
          maxItems: 1000
          uniqueItems: true
          items:
            type: string
            maxLength: 512
            minLength: 1
    ObserveFunnelHistoryPositionsRoot:
      type: object
      required:
        - baseline
        - current
        - differences
      properties:
        baseline:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'
        current:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'
        differences:
          type: object
          additionalProperties:
            type:
              - number
              - 'null'
            format: double
        likeForLike:
          $ref: '#/components/schemas/ObserveFunnelHistoryLikeForLike'
    ObserveFunnelHistoryPosition:
      type: object
      required:
        - selection
        - requested
        - trafficStatus
        - coverage
        - baseline
        - current
        - differences
      properties:
        selection:
          $ref: '#/components/schemas/ObserveFunnelHistorySelection'
        requested:
          type: boolean
          description: True for request selections
        trafficStatus:
          $ref: '#/components/schemas/ObserveFunnelHistoryTrafficStatus'
        coverage:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodCoverage'
        baseline:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'
        current:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'
        differences:
          type: object
          additionalProperties:
            type:
              - number
              - 'null'
            format: double
        unavailableMetrics:
          type: object
          additionalProperties:
            type: string
          description: >-
            Discovered positions only. Requested metrics returned as null, with
            the reason. Request the position in selections for all metrics.
        availableCounters:
          type: array
          items:
            type: string
          description: >-
            Discovered positions only. The totals counters that are populated;
            all others are not calculated and read 0.
    ObserveFunnelHistoryComparisonResult:
      type: object
      required:
        - baseline
        - current
        - differences
      properties:
        baseline:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'
        current:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'
        differences:
          type: object
          description: >-
            Current minus baseline per metric. Rate differences are percentage
            points, duration differences are seconds, count differences are
            absolute. Null when either period metric is unavailable.
          additionalProperties:
            type:
              - number
              - 'null'
            format: double
    ObserveFunnelHistoryCounts:
      type: object
      required:
        - flowsReached
        - attemptsReached
        - completedFlows
        - flowsWithErrors
        - sourceAttempts
      properties:
        flowsReached:
          type: number
          format: double
          description: Distinct weighted flows matching the target across selected attempts
        attemptsReached:
          type: number
          format: double
          description: Weighted selected attempts reaching the node or traversing the edge
        completedFlows:
          type: number
          format: double
          description: Matching flows with eventual complete outcome
        skippedFlows:
          type: number
          format: double
          description: Matching flows eventually skipped or hidden or auto-skipped
        droppedFlows:
          type: number
          format: double
          description: Matching flows with eventual incomplete outcome
        flowsWithErrors:
          type: number
          format: double
          description: Matching flows with at least one error anywhere in the flow
        sourceAttempts:
          type: number
          format: double
          description: >-
            All selected attempts reaching the source, including those not
            taking the edge
        completedAttempts:
          type: number
          format: double
        occurrences:
          type: number
          format: double
        subflowOccurrences:
          type: number
          format: double
        completedSubflowOccurrences:
          type: number
          format: double
        completedHere:
          type: number
          format: double
        droppedHere:
          type: number
          format: double
        retriedHere:
          type: number
          format: double
        continued:
          type: number
          format: double
        otherEndings:
          type: number
          format: double
          description: >-
            Final attempts ending skipped or hidden or auto-skipped at this
            position
        flowsWithRetries:
          type: number
          format: double
        repeatedFlows:
          type: number
          format: double
        embeddedErrorOccurrences:
          type: number
          format: double
          description: Observed references only; not a historically complete error count
        completionDurationBuckets:
          type: array
          minItems: 6
          maxItems: 1000
          items:
            type: number
            format: double
          description: le3s, le10s, le30s, le1m, le5m, g5m for eventual completed flows
        completedHereDurationBuckets:
          type: array
          minItems: 6
          maxItems: 1000
          items:
            type: number
            format: double
          description: Same bands for flows completed at this target
    ObserveFunnelHistoryMetricValue:
      x-go-type: any
      oneOf:
        - type: number
          format: double
        - $ref: '#/components/schemas/ObserveFunnelHistoryRate'
        - $ref: '#/components/schemas/ObserveFunnelHistoryDurationSummary'
        - type: 'null'
    ObserveFunnelHistoryBreakdownResult:
      type: object
      required:
        - dimension
        - groups
      description: >-
        One independent grouping of the top-level filtered population. Shares
        the top-level baseline, dates, coverage and unavailable-metric
        semantics; dimensions are not nested.
      properties:
        dimension:
          type: string
        groups:
          type: array
          items:
            $ref: '#/components/schemas/ObserveFunnelHistoryMetricGroup'
    ObserveFunnelHistoryStep:
      type: object
      additionalProperties: false
      required:
        - kind
      description: >-
        Exactly one discriminator-specific field: decisionID, subflowType,
        flowType or terminalType. specType is exact structural identity, not a
        wildcard, and is supported only on split subflow types. Decision
        input/output values do not split the structural node. Predicates on
        choices are future work.
      properties:
        kind:
          type: string
          enum:
            - decision
            - subflow
            - flow
            - terminal
        decisionID:
          type: string
          pattern: ^dec-[0-9]+$
        subflowType:
          type: string
          enum:
            - provideIdentifier
            - passwordLogin
            - passkeyLogin
            - passkeyEnrollment
            - socialLogin
            - ssoLogin
            - emailLink
            - emailOtp
            - smsOtp
            - totp
            - appConfirmation
            - provideData
            - setPassword
            - passkeyDeletion
            - reset
            - systemCredential
            - trustedDeviceCheck
            - trustedDeviceEnrollment
            - keySigning
            - keyRegistration
            - form
        flowType:
          type: string
          description: Built-in or project-defined flow type from the project catalog
        specType:
          type: string
        terminalType:
          type: string
          enum:
            - decision-unresolved
            - decision-resolved
          description: >-
            Synthetic ending after a final decision; must be last in an exact
            prefix.
    ObserveFunnelHistoryPeriod:
      type: object
      additionalProperties: false
      required:
        - fromDate
        - toDate
      properties:
        fromDate:
          type: string
          description: >-
            Inclusive UTC-naive datetime aligned to a project calendar-day
            boundary
        toDate:
          type: string
          description: >-
            Exclusive UTC-naive datetime aligned to a project calendar-day
            boundary
    ObserveFunnelHistoryBrowserHierarchyFilter:
      type: object
      additionalProperties: false
      required:
        - mode
        - section
        - browser
      properties:
        mode:
          type: string
          enum:
            - os
            - device
        section:
          type: string
          maxLength: 512
          minLength: 1
        browser:
          type: string
          maxLength: 512
          minLength: 1
      description: >-
        Exact existing OS/browser or derived-device/browser cohort. Unknown
        labels use (unknown); device sections are desktop, mobile or other.
    ObserveFunnelHistoryPeriodResult:
      type: object
      required:
        - fromDate
        - toDate
        - completeToDate
        - provisional
        - totals
        - summary
        - unparsedRows
      properties:
        fromDate:
          type: string
        toDate:
          type: string
        completeToDate:
          type: string
          description: >-
            Exclusive end of completed calendar days within this period, in UTC
            without a timezone suffix.

            Calculated using the project timezone at request time. Equals
            fromDate when no day has finished.

            Use days before this boundary for daily traffic-support and
            start/stop checks. This is a calendar

            boundary, not a guarantee that all events for those days have
            arrived.
        provisional:
          type: boolean
          description: >-
            True when the period includes an unfinished or future calendar day.
            Totals, rates and daily

            buckets still include all observations received for the requested
            period and may change.
        totals:
          $ref: '#/components/schemas/ObserveFunnelHistoryCounts'
        summary:
          type: object
          description: >-
            Metrics from merged period counts and duration histograms, never
            averages of daily percentages or medians. Null when this period has
            unparsed candidates; counts then cover decoded rows only.
          additionalProperties:
            $ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'
        unparsedRows:
          type: integer
          format: int64
    ObserveFunnelHistoryLikeForLike:
      type: object
      required:
        - baseline
        - current
        - differences
        - excludedFlows
      description: >-
        Overall funnel comparison after excluding flows that reach positions
        classified as increased, decreased, started-within-period or
        stopped-within-period. Use it alongside the full comparison to see how
        these routes affect the overall result. Includes flow counts and
        eventual completion, drop-off and skip rates. Omitted when either period
        contains paths that could not be interpreted. This comparison does not
        establish the cause of a change.
      properties:
        baseline:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'
        current:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodResult'
        differences:
          type: object
          additionalProperties:
            type:
              - number
              - 'null'
            format: double
        excludedFlows:
          type: object
          required:
            - baseline
            - current
          properties:
            baseline:
              type: number
              format: double
            current:
              type: number
              format: double
    ObserveFunnelHistoryTrafficStatus:
      type: string
      enum:
        - comparable
        - increased
        - decreased
        - started-within-period
        - stopped-within-period
        - insufficient-data
      description: >-
        Describes how traffic is distributed across completed calendar days in
        the two periods. Unfinished and future days are excluded from
        classification. A period with no completed days is insufficient-data.
        Totals and rates still include all received observations. These
        classifications are independent of changes in authentication
        performance.


        - increased: the current period has enough traffic, the baseline does
        not and baseline traffic per day is at most 25% of current traffic.

        - decreased: the baseline has enough traffic, the current period does
        not and current traffic per day is at most 25% of baseline traffic.

        - started-within-period: traffic is absent for at least two days at the
        start of one period, then averages at least 100 flows per active day.
        The other period has traffic at that edge.

        - stopped-within-period: the corresponding gap occurs at the end of one
        period.

        - comparable: both periods have enough traffic and neither has a
        qualifying start or end gap. Volume and completion rates may still
        differ.

        - insufficient-data: there is not enough evidence for another
        classification, or a positions request contains paths that could not be
        interpreted.


        Enough traffic means at least 1,000 flows per seven days, scaled to each
        period's length. For positions output, discovery.minFlows can change
        this threshold. Step-category groups use occurrences instead of flows.

        Increased and decreased describe changes between low and substantial
        traffic; neither means the smaller period had zero traffic. They do not
        report every change in volume.
    ObserveFunnelHistoryPeriodCoverage:
      type: object
      required:
        - baseline
        - current
      properties:
        baseline:
          $ref: '#/components/schemas/ObserveFunnelHistoryCoverageDays'
        current:
          $ref: '#/components/schemas/ObserveFunnelHistoryCoverageDays'
    ObserveFunnelHistoryRate:
      type: object
      required:
        - numerator
        - denominator
        - percent
      properties:
        numerator:
          type: number
          format: double
        denominator:
          type: number
          format: double
        percent:
          type:
            - number
            - 'null'
          format: double
          description: Null when denominator is zero
    ObserveFunnelHistoryDurationSummary:
      type: object
      properties:
        histogram:
          type: object
          additionalProperties:
            type: number
            format: double
        observations:
          type: number
          format: double
        estimatedP50Seconds:
          type:
            - number
            - 'null'
          format: double
          x-omitempty: false
        method:
          type: string
      description: >-
        Same six flow-duration bands as the funnel. Linear interpolation; the
        >5m band assumes 300–600 seconds. This is an estimate of end-to-end
        completion time, not elapsed time within the node.
    ObserveFunnelHistoryMetricGroup:
      type: object
      required:
        - value
        - buckets
        - totals
        - summary
      properties:
        comparison:
          $ref: '#/components/schemas/ObserveFunnelHistoryComparisonResult'
        trafficStatus:
          $ref: '#/components/schemas/ObserveFunnelHistoryTrafficStatus'
        coverage:
          $ref: '#/components/schemas/ObserveFunnelHistoryPeriodCoverage'
        value:
          type: string
        totals:
          $ref: '#/components/schemas/ObserveFunnelHistoryCounts'
        summary:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'
        buckets:
          type: array
          items:
            type: object
            properties:
              time:
                type: string
                format: date-time
              counts:
                $ref: '#/components/schemas/ObserveFunnelHistoryCounts'
              unparsedRows:
                type: integer
                format: int64
                description: Nonzero makes every metric in this bucket unavailable
              unparsedWeight:
                type: number
                format: double
                description: Candidate flow weight that could not be interpreted
              values:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/ObserveFunnelHistoryMetricValue'
    ObserveFunnelHistoryCoverageDays:
      type: object
      required:
        - days
        - activeDays
        - materialDays
        - volume
      description: >-
        Daily presence within the requested comparison period, including
        observations received on unfinished

        days. Volume is flows, or occurrences for step-category groups. Traffic
        classification uses only

        completed days; the period result's completeToDate identifies that
        boundary.
      properties:
        days:
          type: integer
        activeDays:
          type: integer
          description: Days with any volume
        materialDays:
          type: integer
          description: Days with at least 100
        volume:
          type: number
          format: double
        firstDay:
          type: string
          format: date
          description: First project-local day with volume
        lastDay:
          type: string
          format: date
          description: Last project-local day with volume
  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.