> ## 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: 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/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 UTC-naive datetime; later than fromDate; maximum 366 days 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; no position discovery is supported. output: type: string enum: - buckets - totals default: buckets description: >- Single selection supports buckets only (the default). Plural selections requires totals, returning no buckets and accepting no comparison or breakdowns. Interval still selects the existing daily/hourly source data. selections: type: array minItems: 1 maxItems: 1000 description: >- Explicit node/edge prefixes to calculate together with output totals. Mutually exclusive with selection. Non-root positions are returned in nodes, including zero-volume positions. Root remains the top-level result. items: $ref: '#/components/schemas/ObserveFunnelHistorySelection' comparison: $ref: '#/components/schemas/ObserveFunnelHistoryComparison' filters: $ref: '#/components/schemas/ObserveFunnelHistoryFilters' breakdowns: type: array minItems: 1 maxItems: 16 description: >- Independent first-order groupings calculated together in one pass over stored aggregates. Each dimension occurs once. Omit a dimension's values to discover its observed groups in that same pass. The sum of explicit and discovered values across all dimensions multiplied by the number of buckets must not exceed 100000. The baseline is returned once at the top level. 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' 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: 16 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' 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-` 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..6; 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 - customTag1 - customTag2 - customTag3 - customTag4 - customTag5 - customTag6 - 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, applies to its two periods, scaled by period 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 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 - emailLink - emailOtp - smsOtp - totp - appConfirmation - provideData - setPassword - passkeyDeletion - reset - systemCredential - trustedDeviceCheck - trustedDeviceEnrollment - keySigning - keyRegistration 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 - totals - summary - unparsedRows properties: fromDate: type: string toDate: type: string 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 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' 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' 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. ````