Goals and funnels

The conversion model behind the reports. Listing funnels and running one are on the read surface; these are the writes, plus the goal list that gives you ids to work with.

Method	Path	Permission
`GET`	`/sites/{id}/goals`	Read analytics
`POST`	`/sites/{id}/goals`	Manage sites
`PUT`	`/sites/{id}/goals/{goalId}`	Manage sites
`DELETE`	`/sites/{id}/goals/{goalId}`	Manage sites
`POST`	`/sites/{id}/funnels`	Manage sites
`PUT`	`/sites/{id}/funnels/{funnelId}`	Manage sites
`DELETE`	`/sites/{id}/funnels/{funnelId}`	Manage sites

Writes are owner only. A shared site answers 403 not_site_owner.

List goals

GET /api/v1/sites/{id}/goals

What the site measures, as configured. For how those goals performed, query the event:goal dimension through /query.

Create a goal

POST /api/v1/sites/{id}/goals

A goal is one of three things: a custom event, a page, or a scroll depth. A scroll depth goal is event_name engagement plus scroll_depth. A goal needs an event_name or a path. An empty event_name, a scroll_depth on any other event, or a regex that doesn't compile is 400 invalid_request.

Field	Notes
`name`	Required. Shown in reports
`event_name`	A custom event the site sends
`path`	A page path, paired with `operator`
`operator`	`e` equals, `b` begins with, `c` contains, `r` regular expression (RE2: no lookaround, no backreferences)
`scroll_depth`	Percent scrolled, 1 to 100. Only with `event_name` `engagement`

curl -s -X POST https://statable.com/api/v1/sites/3195799/goals \
  -H "Authorization: Bearer stbl_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Signup", "path": "/thanks", "operator": "e"}'

A duplicate name is 409 goal_exists.

Replace a goal

PUT /api/v1/sites/{id}/goals/{goalId}

Sends the whole definition. A field you leave out is cleared, not kept, so read the goal first and send it back with your edit applied.

DELETE answers 204. Deleting one that is already gone is 404 goal_not_found. A goal that a funnel step still uses is 409 goal_in_use, and the message names the funnel. Remove the step first.

Create a funnel

POST /api/v1/sites/{id}/funnels

An ordered list of two or more steps.

Field	Notes
`name`	Required. A duplicate is `409 funnel_exists`
`steps`	Required, two or more
`scope`	`visitor` by default, or `session`
`strict_order`	When true the steps must occur in exactly this order with nothing between

curl -s -X POST https://statable.com/api/v1/sites/3195799/funnels \
  -H "Authorization: Bearer stbl_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Signup flow",
       "steps": [{"kind": "page", "path": "/"},
                 {"kind": "goal", "goal_id": 12}]}'

Each step carries a kind, and that decides which other fields apply.

`kind`	Other fields
`page`	`path`, `operator` (`e` equals, `b` begins with, `c` contains, `r` regex (RE2; one that doesn't compile is `400`))
`entry_page` `exit_page`	`path`
`event`	`event`, optionally `prop_key` and `prop_value`
`goal`	`goal_id`
`scroll`	the depth to reach

A step pointing at a goal this site does not have is 400, and the error names the step.

The answer has the same shape as GET /funnels, so a funnel you just created can be run through POST /funnels/{id}/report without fetching it again.

Replace a funnel

PUT /api/v1/sites/{id}/funnels/{funnelId}

Replaces the definition including every step. Steps you leave out are removed, not kept.

DELETE answers 204. An unknown id is 404 unknown_funnel.

strict_order changes what a report means

With it off, a visitor who did the steps in a different order still counts. Turn it on only when the sequence itself is the thing you are measuring, and remember that a saved funnel's reports before and after the change are not comparable.

Next steps

Manage sites for provisioning and settings
Goals for what a goal means in the dashboard
Errors for every code these endpoints return

Ready to take control of your web analytics? Try Statable free for 30 days. No credit card required, full feature access, built for GDPR. Start your free trial or view a live demo.