Skip to content

API reference Funnels

API reference

Funnels

The API operations about funnels, each with its input, its output and an example.

The operations about funnels. Each one is a POST with a JSON object as its body: Making a request has the rules they share.

Create funnel #

POST /api/v1/funnels.create · Write

Saves a funnel for one site: a name and an ordered list of steps a visitor has to do. It appears on the Funnels page of the dashboard at once. 2 to 5 steps in order, each { "type": "pageview" or "event", "value": text }. Two neighbouring steps may not be the same, and an event step may not use a name the tracker keeps for itself (pageview, 404 and the names with its own prefix). The name must be unique on the site, ignoring case (409 taken), and a site holds at most 50 funnels (409 limit_reached). A step that breaks a rule answers 400 invalid with the step named, for example steps.1. Page paths are cleaned up like recorded paths, so read the steps in the answer. Needs a token with the Write permission. To try steps without saving, call funnels.report with steps.

Input #

Field Type Required Description
siteId string required The site id, from sites.list.
name string, 1 to 80 characters required The name of the funnel, 1 to 80 characters. Unique on the site, ignoring case.
steps array of object, 2 to 5 items required 2 to 5 steps in order, each { "type": "pageview" or "event", "value": text }. Two neighbouring steps may not be the same, and an event step may not use a name the tracker keeps for itself (pageview, 404 and the names with its own prefix).

Fields of steps

Field Type Required Description
type "pageview" | "event" required pageview for a page, event for a custom event.
value string, 1 to 512 characters required For a page: its path, for example /pricing; a trailing * matches every path that starts with it. For an event: its exact name.

Output #

Field Type Present Description
id string always The funnel id. Pass it to funnels.report as funnelId.
name string always The name the funnel was saved under.
steps array of object always The steps as they were saved, in order. A page step is cleaned up like a recorded path, so it may differ from what was sent.
createdAt number always When the funnel was created, milliseconds since 1970 UTC.
updatedAt number always When the funnel was last changed, milliseconds since 1970 UTC.

Example #

curl -s -X POST https://clearsaga.com/api/v1/funnels.create \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","name":"Signup","steps":[{"type":"pageview","value":"/pricing"},{"type":"event","value":"Signup"}]}'

Run clearsaga help funnels create for one flag per field.

Delete funnel #

POST /api/v1/funnels.delete · Write

Removes a saved funnel from one site for good: its name and its steps. This cannot be undone. To change a funnel and keep it, call funnels.update instead. The id comes from funnels.list. Only the definition goes. No recorded visit is touched: a report is computed from recorded hits when it is asked for, so saving the same steps again with funnels.create gives the same numbers for every past period. The alert rules that watch the funnel are removed with it, together with their delivery logs. An id the site does not have is not an error: the answer says deleted false and nothing was changed, so sending the same call twice is safe. Needs a token with the Write permission.

Input #

Field Type Required Description
siteId string required The site id, from sites.list.
id string, at least 1 characters required The id of the funnel to remove, from funnels.list.

Output #

Field Type Present Description
id string always The id that was sent.
deleted boolean always true when the funnel was there and this call removed it. false when the site has no funnel with that id, because it was removed before or the id is wrong: nothing was changed, and that is not an error.
name string | null always The name the funnel had, so it is clear what was removed. Null when deleted is false.

Example #

curl -s -X POST https://clearsaga.com/api/v1/funnels.delete \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"FUNNEL_ID"}'

Run clearsaga help funnels delete for one flag per field.

Duplicate funnel #

POST /api/v1/funnels.duplicate · Write

Saves a copy of a funnel on the same site, with the same steps and the name "Copy of" followed by the original name (a number is added when that name is taken). The id comes from funnels.list. Use it to try a variation: copy, then change the copy with funnels.update. Every call makes another copy. An unknown id answers 404, and a site that already holds 50 funnels answers 409 limit_reached. Needs a token with the Write permission.

Input #

Field Type Required Description
siteId string required The site id, from sites.list.
id string, at least 1 characters required The id of the funnel to copy, from funnels.list.

Output #

Field Type Present Description
id string always The funnel id. Pass it to funnels.report as funnelId.
name string always The name the funnel was saved under.
steps array of object always The steps as they were saved, in order. A page step is cleaned up like a recorded path, so it may differ from what was sent.
createdAt number always When the funnel was created, milliseconds since 1970 UTC.
updatedAt number always When the funnel was last changed, milliseconds since 1970 UTC.

Example #

curl -s -X POST https://clearsaga.com/api/v1/funnels.duplicate \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"FUNNEL_ID"}'

Run clearsaga help funnels duplicate for one flag per field.

List funnels #

POST /api/v1/funnels.list · Read

The saved funnels of one site, the one changed last first: each with its id, name and ordered steps. Get the siteId from sites.list first. The whole list comes at once (a site holds at most 50 funnels); there is no paging, no range and no filter. It lists definitions only. For how many visitors got through a funnel, pass its id to funnels.report as funnelId. Keeps working while the workspace is locked.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

Input #

Field Type Required Description
siteId string required The site id, from sites.list.

Output #

Field Type Present Description
rows array of object always The saved funnels of the site, the one changed last first: id (pass it to funnels.report as funnelId), name, the steps in order, and createdAt and updatedAt in milliseconds since 1970 UTC.

Example #

curl -s -X POST https://clearsaga.com/api/v1/funnels.list \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

Run clearsaga help funnels list for one flag per field.

Funnel report #

POST /api/v1/funnels.report · Read

How many visitors got through a funnel in a period, step by step: who entered, who reached each step, where they dropped off, and the overall conversion. Send exactly one of funnelId (a saved funnel, from funnels.list or funnels.create) or steps (a list to try without saving); sending both or neither answers 400. A visitor counts for a step when they did it after the step before, on the same day. Rates are fractions from 0 to 1. The page, event, property and conversion filters cannot apply to a funnel, in any of their forms (path, path.not and path.has alike): they change nothing, and the answer names each once by its plain key in ignoredFilters. The other filters apply. An unknown funnelId answers 404, and steps that break a rule answer 400 invalid with the step named. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

Input #

Field Type Required Description
siteId string required The site id, from sites.list.
range "today" | "yesterday" | "30m" | "12h" | "24h" | "week" | "7d" | "30d" | "60d" | "90d" | "mtd" | "ytd" | "12mo" | "all" | "custom" optional The period to report on: one of today, yesterday, 30m, 12h, 24h, week, 7d, 30d, 60d, 90d, mtd, ytd, 12mo, all. Left out, the workspace's default range is used (30d unless it was changed). For exact dates send from and to and leave range out (custom is accepted with them and means the same). A preset together with dates answers 400.
from string optional First day of a custom period, YYYY-MM-DD in the site's time zone. Send it together with to: one without the other answers 400, and so does a day that does not exist or a from after to. A day after today is read as today; window in the answer shows the period that was used.
to string optional Last day of a custom period, inclusive, YYYY-MM-DD in the site's time zone. Send it together with from.
compare "prev" | "week" | "month" | "quarter" | "year" | "custom" | "off" optional What the period is compared with: prev (the period just before, the default), week, month, quarter or year earlier, custom (cfrom and cto are then required), or off for no comparison. The range all never has a comparison.
cfrom string optional First day of a custom comparison period, YYYY-MM-DD. Required with compare set to custom, where a day that does not exist or a cfrom after cto answers 400.
cto string optional Last day of a custom comparison period, inclusive, YYYY-MM-DD. Required with compare set to custom.
filters object optional Narrow the numbers to matching traffic. An object such as { "country": "us", "path.has": "pricing" }. A plain key means "is"; a key ending in .not means "is not" and a key ending in .has means "contains". Filters are joined with AND. At most 10 keys, of which at most 3 may end in .has. Default: {}. The filter keys are listed under Filters.
funnelId string, at least 1 characters optional The id of a saved funnel. Send this or steps, never both.
steps array of object, 2 to 5 items optional Steps to report on without saving a funnel. Send this or funnelId, never both. 2 to 5 steps in order, each { "type": "pageview" or "event", "value": text }. Two neighbouring steps may not be the same, and an event step may not use a name the tracker keeps for itself (pageview, 404 and the names with its own prefix).

Fields of steps

Field Type Required Description
type "pageview" | "event" required pageview for a page, event for a custom event.
value string, 1 to 512 characters required For a page: its path, for example /pricing; a trailing * matches every path that starts with it. For an event: its exact name.

Output #

Field Type Present Description
serverNow number always The clock the period was resolved with: the start of the next whole minute, milliseconds since 1970 UTC.
serverTime number always When the answer was built, milliseconds since 1970 UTC.
window object always The period the numbers cover: from and to in milliseconds since 1970 UTC (to is exclusive), the time zone, a label and the bucket size.
compare object | null always The comparison period (from, to, tz, label, granularity, token) with completed, the visitors who completed the funnel in it, and totalConversion, their share of those who entered. Null when there is no comparison.
rawFrom number | null always The earliest time detailed data is kept from, or null when nothing was trimmed.
truncated boolean always True when a filtered answer could only cover the part of the period that still has detailed data.
steps array of object always One row per step, in order: visitors who reached it, cumulativeRate (share of those who entered), stepRate (share of the step before), dropoffRate and dropped (lost since the step before). Rates are fractions from 0 to 1.
entered number always Visitors who did the first step.
completed number always Visitors who did every step in order.
totalConversion number | null always completed divided by entered, a fraction from 0 to 1. Null when nobody entered.
ignoredFilters array of string always The filters of the input that a funnel cannot apply and left out: the page, event, property and conversion filters. A filter is named once by its plain key, whichever form was sent: path.has and path.not are both listed as path.

Example #

curl -s -X POST https://clearsaga.com/api/v1/funnels.report \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","steps":[{"type":"pageview","value":"/pricing"},{"type":"event","value":"Signup"}]}'

Run clearsaga help funnels report for one flag per field.

Update funnel #

POST /api/v1/funnels.update · Write

Replaces the name and the steps of a saved funnel. Send both in full: a step that is left out is removed. The id comes from funnels.list or funnels.create. Reports are computed from recorded hits when they are asked for, so the change applies to every past period at once and nothing is lost by it. 2 to 5 steps in order, each { "type": "pageview" or "event", "value": text }. Two neighbouring steps may not be the same, and an event step may not use a name the tracker keeps for itself (pageview, 404 and the names with its own prefix). The name must be unique on the site, ignoring case (409 taken). A step that breaks a rule answers 400 invalid with the step named, for example steps.1, and an unknown id answers 404. Page paths are cleaned up like recorded paths, so read the steps in the answer. Sending the same input twice leaves the funnel as it is. Needs a token with the Write permission.

Input #

Field Type Required Description
siteId string required The site id, from sites.list.
id string, at least 1 characters required The id of the funnel to change, from funnels.list.
name string, 1 to 80 characters required The new name of the funnel, 1 to 80 characters. Unique on the site, ignoring case. Send the current name to keep it.
steps array of object, 2 to 5 items required The new steps, replacing the old ones. 2 to 5 steps in order, each { "type": "pageview" or "event", "value": text }. Two neighbouring steps may not be the same, and an event step may not use a name the tracker keeps for itself (pageview, 404 and the names with its own prefix).

Fields of steps

Field Type Required Description
type "pageview" | "event" required pageview for a page, event for a custom event.
value string, 1 to 512 characters required For a page: its path, for example /pricing; a trailing * matches every path that starts with it. For an event: its exact name.

Output #

Field Type Present Description
id string always The funnel id. Pass it to funnels.report as funnelId.
name string always The name the funnel was saved under.
steps array of object always The steps as they were saved, in order. A page step is cleaned up like a recorded path, so it may differ from what was sent.
createdAt number always When the funnel was created, milliseconds since 1970 UTC.
updatedAt number always When the funnel was last changed, milliseconds since 1970 UTC.

Example #

curl -s -X POST https://clearsaga.com/api/v1/funnels.update \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"FUNNEL_ID","name":"Signup","steps":[{"type":"pageview","value":"/pricing"},{"type":"event","value":"Signup"}]}'

Run clearsaga help funnels update for one flag per field.