Skip to main content
POST
Calculate historical metrics for an exact journey position

Authorizations

Authorization
string
header
required

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.

Body

application/json
schemaVersion
enum<string>
required
Available options:
funnel-metric-v1
name
enum<string>
required
Available options:
login-flow-v1,
signup-flow-v1,
recovery-flow-v1,
security-enrollment-flow-v1
fromDate
string
required

Inclusive UTC-naive datetime, YYYY-MM-DDTHH:mm:ss; aligned to project bucket boundaries

toDate
string
required

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
enum<string>
required
Available options:
daily,
hourly
metrics
enum<string>[]
required
Required array length: 1 - 19 elements
Available options:
flowsReached,
attemptsReached,
occurrences,
eventualCompletionRate,
attemptCompletionRate,
flowErrorRate,
retriedFlowRate,
eventualCompletionTime,
subflowCompletionRate,
completedHereRate,
dropoffRate,
retryHereRate,
continueRate,
completedHereTime,
stepErrorRate,
edgeShare,
eventualSkipRate,
eventualDropoffRate,
skippedHereRate
selection
object

Required for single-position bucket history. Mutually exclusive with selections. Omission requires selections with output totals, or output positions (selections optional there).

output
enum<string>
default:buckets

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.

Available options:
buckets,
totals,
positions
selections
object[]

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.

Required array length: 1 - 1000 elements
comparison
object

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.

discovery
object

With positions output, include additional routes whose traffic changed, even when they are absent from the current funnel view.

filters
object

Values within a dimension are ORed; dimensions are ANDed. Omitted filters mean all. Null includes rows where a supported dimension is absent or empty.

breakdowns
object[]

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.

Required array length: 1 - 30 elements

Response

Daily or hourly metrics, including empty buckets

schemaVersion
string
required
projectID
string
required
name
string
required
timeZone
string
required
timeBasis
enum<string>
required
Available options:
flow-start
selection
object
required
totals
object
required
summary
object
required

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.

buckets
object[]
required
coverage
object
required
nodes
array

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.

root
object
positions
object[]

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.

extrasTruncated
integer

Output positions only. Discovered non-stable positions beyond discovery.maxExtra

comparison
object
breakdowns
object[]

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.

Maximum array length: 30
unavailableMetrics
object

Reasons for unavailable or inapplicable metrics; corresponding values are null

diagnostics
object

Calculation timings and processed-cell counts. Shard timings overlap and must not be added as end-to-end latency.