Funnels API

Measure one complete attempt

An attempt starts when the entire first required step is satisfied. That event starts the conversion window and supplies cohort properties. An unfinished first group is not a started attempt; use separate steps to measure losses within the group.

Create up to 20 required conversion steps and 30 total steps. Choose Attempts in the funnel editor and set the property carrying your attempt ID. Existing funnels continue counting visitors.

Send one opaque attempt ID on every required event, including completion. Keep it when resuming across sessions and replace it when restarting. Missing IDs cannot advance the funnel. A repeated screen requires a new event.

Use original occurrence timestamps for offline events. Equal timestamps require distinct increasing values in the configured sequence property to prove step order. Reuse the same ingestion dedupeKey for delivery retries when sending events through the tracking API.

Set cohort properties on the event that completes the first required step. Configure up to three properties, such as flow version, app version, and paywall variant, to compare their combinations. Missing entry values remain Unknown even if a later event supplies them.

Assign paywall variants before the journey starts to compare end-to-end conversion fairly. An app upgrade during a resumed attempt stays in its entry version cohort. Later conflicting values are reported without moving the attempt.

The reporting period selects attempts by their first required step. Completion can occur after the reporting period within the saved conversion window. Pending attempts have time remaining; confirmed drop-off counts only expired incomplete attempts.

Filter and compare entry cohorts, inspect each transition, and export all matching cohorts. Rates with no denominator show no data. Retained history may be incomplete after deletion or partial imports. Attempt reports do not attribute revenue.

Provider events need an explicit matching attempt ID and a verified visitor link. A shared customer ID alone does not prove that a payment belongs to the same attempt.

After entry, an event with a sequence number no greater than the last accepted number is skipped. Later valid events can continue the attempt. If tied starting events have no usable order and disagree on a cohort value, that value stays Unknown; agreeing values are kept. Ordering issues are reported.

Exports include pending attempts after each step and median completion time in minutes for each result group. A group with no completed attempts has no median completion time.

Attempt funnels default to seven days and require a finite conversion window. Supported durations are one hour, one day, seven days, fourteen days, thirty days, and ninety days. Saving changes recalculates retained history.

Read saved funnel results

GET /api/funnels/:id/results accepts the workspace API key, optional websiteId, paired startAt and endAt timestamps, page (default 1), and pageSize (1–100, default 20). Attempt responses include aggregate step counts, paginated cohorts, definition revision, evaluation time, and coverage information.

Pass cohort as a JSON object with exact typed entry values, such as {"flow_version":"v3","paywall_variant":null}. null selects missing values, not the literal string Unknown. Aggregates cover every matching cohort regardless of pagination; data-quality totals cover all entry cohorts.

Use the Funnels API to create the same saved funnel definitions available in the Conversions dashboard. Create an API key from Settings > API Keys, then send it as a bearer token.

1curl https://usegrometrics.com/api/settings/api-keys \2  -H "Content-Type: application/json" \3  -b "grometrics_session=YOUR_SESSION_COOKIE" \4  -d '{ "name": "Momenta setup" }'

1curl https://usegrometrics.com/api/funnels \2  -H "Authorization: Bearer YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Momenta onboarding",6    "conversionWindowSeconds": 1209600,7    "steps": [8      { "type": "Screen view", "value": "Onboarding Hook" },9      { "type": "Screen view", "value": "Onboarding First Action" },10      { "type": "Screen view", "value": "Onboarding Paywall" },11      { "type": "Event", "value": "paywall_viewed" },12      { "type": "Event", "value": "trial_started" },13      { "type": "Event", "value": "onboarding_completed" }14    ]15  }'

For OR steps, put the fallback matches in steps[].or. For all-of groups, set mode to all_of on the parent step; Grometrics then requires the parent step and every OR row in any order.

Required steps define conversion. Diagnostic rows report matching context without gating progression. One event can complete a required step and populate a matching diagnostic row, such as a failure reason.

1{2  "steps": [3    {4      "type": "Event",5      "value": "first_project_created",6      "or": [{ "type": "Event", "value": "template_imported" }]7    },8    {9      "type": "Event",10      "value": "message_sent",11      "filters": [{ "property": "is_first_message", "operator": "equals", "value": "true" }],12      "or": [{ "type": "Event", "value": "invite_accepted" }]13    },14    {15      "type": "Event",16      "value": "profile_name_added",17      "mode": "all_of",18      "or": [19        { "type": "Event", "value": "profile_photo_added" },20        { "type": "Event", "value": "profile_role_selected" },21        { "type": "Event", "value": "profile_bio_added" },22        { "type": "Event", "value": "profile_topics_selected" }23      ]24    }25  ]26}