Funnels API
Create saved funnels from scripts, setup tools, or internal dashboards.
Last updated June 3, 2026
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.
Create API key
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" }'
POST /api/funnels
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.
advanced-funnel-steps.json
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}
Options / Configuration
| Option | Type | Required | Description |
|---|---|---|---|
| name | string | ✓ | Saved funnel name |
| steps | array | ✓ | 2 to 10 conversion steps, plus optional diagnostic steps |
| steps[].type | string | ✓ | Pageview, Screen view, Goal, Event, or Transaction |
| steps[].value | string | ✓ | Page path, screen name, saved goal name, custom event name, or transaction event |
| steps[].filters | array | no | Property filters such as [{ "property": "is_first_message", "operator": "equals", "value": "true" }] |
| steps[].or | array | no | Alternative step matches. The first matching option counts for this step. |
| steps[].mode | string | no | Use all_of when the step requires the main step and every OR alternative in any order. |
| steps[].diagnostic | boolean | no | Shows a diagnostic row without gating progression or counting toward the 10-step conversion cap |
| conversionWindowSeconds | number or null | no | 3600, 86400, 604800, 1209600, 2592000, 7776000, or null |
What happens next
After creating a funnel, open Conversions and switch to Funnels to review drop-off, source breakdowns, and revenue after completion.
Troubleshooting
Request is unauthorized
Check that the Authorization header uses a valid, unrevoked Grometrics API key.
Screen step has no visitors
Confirm the mobile SDK sends the same screen value used in the funnel step.
Was this page helpful?