Conversion goals

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

Conversion rate breakdown #

POST /api/v1/goals.breakdown · Read

The conversion rate of one goal split by a dimension, for one site and period: of the visitors from each source, country, page and so on, how many completed the goal. dimension is one of page, entry_page, exit_page, referrer, channel, ai_tool, hostname, country, region, city, browser, os, device. Get the siteId from sites.list first and the goal name from goals.list. goal is the exact name of a goal that is switched on; any other name answers an empty list, not an error. It answers the top rows only, most visitors first: limit rows (8 unless set, 100 at most). There is no offset and no total field. A converter is counted in a row when the visitor was in that row and completed the goal anywhere in the period. Rows match the rows of overview.breakdown for the same dimension by key. On the city dimension each row also carries country and regionCode, because two cities of the same name in different regions are two rows with the same key and label. The conversion filter is ignored here, because the rate is measured against all visitors of the row; every other filter applies. The comparison is not used and the answer carries no period fields. 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 #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/goals.breakdown \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","goal":"Newsletter signup","dimension":"page"}'

clearsaga goals breakdown --input '{"siteId":"site_abc123def456","goal":"Newsletter signup","dimension":"page"}'

Tool: goals_breakdown
Arguments: {"siteId":"site_abc123def456","goal":"Newsletter signup","dimension":"page"}

Run clearsaga help goals breakdown for one flag per field.

Goal completions #

POST /api/v1/goals.completions · Read

How often each conversion goal of one site was completed in the last 30 days: completions, the visitors who completed it (converters) and the conversion rate, which is converters divided by all visitors of those days. Get the siteId from sites.list first. The period is fixed at the last 30 days in the site's time zone: it takes no range, no comparison and no filter. For another period or a split by source or country call goals.breakdown, or overview.kpis with a conversion filter. A token that can only read gets the goals that are switched on; a token with the Write permission also gets the ones that are off, with what they would count. One row per goal, for the same goals goals.list answers; nothing pages. 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 #

Output #

Example #

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

clearsaga goals completions --input '{"siteId":"site_abc123def456"}'

Tool: goals_completions
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help goals completions for one flag per field.

Create conversion goal #

POST /api/v1/goals.create · Write

Adds a conversion goal to one site, switched on. A goal says what counts as a conversion: a custom event (type event, name is the exact event name) or a view of a page (type page, name is a label and pathPattern is the path). pathPattern must be sent for a page goal and must not be sent for an event goal; anything else answers 400. Goals are applied when a question is asked, so conversion numbers for past periods change at once and nothing is recomputed. The name must be unique among the goals of the site (409 taken), an event goal may not use a name the tracker keeps for itself (400 invalid), and a site holds at most 20 event and page goals (409 limit_reached). The automatic conversions (contact clicks, form submits and the like) are presets and are managed in the dashboard, not here. Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/goals.create \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","type":"page","name":"Reached pricing","pathPattern":"/pricing"}'

clearsaga goals create --input '{"siteId":"site_abc123def456","type":"page","name":"Reached pricing","pathPattern":"/pricing"}'

Tool: goals_create
Arguments: {"siteId":"site_abc123def456","type":"page","name":"Reached pricing","pathPattern":"/pricing"}

Run clearsaga help goals create for one flag per field.

Delete conversion goal #

POST /api/v1/goals.delete · Write

Removes an event goal or a page goal from one site for good. This cannot be undone. To stop counting a goal and keep it, call goals.update with enabled false instead. The id comes from goals.list. Only the rule goes. No recorded hit is touched: goals are applied when a question is asked, so the conversions it counted leave every report at once, for past periods too, and adding the same goal again with goals.create brings them back. The alert rules that watch the goal are removed with it, together with their delivery logs. A saved segment that filters by this goal keeps its other filters; that one is left out for as long as no goal of that name is switched on. When no goal of the site is switched on any more, the campaign reports count every custom event as a conversion (conversionMode events). The automatic conversions (type preset) cannot be deleted: sending the id of one answers 400 invalid with the detail id and removes nothing. They are switched off in the dashboard. 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 #

Output #

Example #

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

clearsaga goals delete --input '{"siteId":"site_abc123def456","id":"GOAL_ID"}'

Tool: goals_delete
Arguments: {"siteId":"site_abc123def456","id":"GOAL_ID"}

Run clearsaga help goals delete for one flag per field.

List conversion goals #

POST /api/v1/goals.list · Read

The conversion goals of one site: what the owner marked as a conversion. A goal is a custom event (type event), a view of a page (type page) or one of the automatic conversions such as contact clicks and form submits (type preset). Get the siteId from sites.list first. The name of a goal is the value the conversion filter and goals.breakdown take. A token that can only read gets the goals that are switched on; a token with the Write permission gets every goal, also the ones that are off, so it can switch them. The whole list comes at once (4 presets and at most 20 event and page goals); there is no paging, no range and no filter. It lists definitions only. For how often each goal was completed call goals.completions. 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 #

Output #

Example #

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

clearsaga goals list --input '{"siteId":"site_abc123def456"}'

Tool: goals_list
Arguments: {"siteId":"site_abc123def456"}

Run clearsaga help goals list for one flag per field.

Update conversion goal #

POST /api/v1/goals.update · Write

Replaces what an event goal or a page goal matches, and can switch it on or off. Send type and name in full, and pathPattern for a page goal; the id comes from goals.list. pathPattern must be sent for a page goal and must not be sent for an event goal; anything else answers 400. enabled switches the goal: false keeps it in the list but counts it nowhere, true counts it again; left out, the goal stays as it is. Goals are applied when a question is asked, so conversion numbers for past periods change at once and switching a goal back on restores them. The automatic conversions (type preset) cannot be changed here: sending the id of one answers 400 invalid with the detail preset. They are managed in the dashboard, because renaming one changes what the tracker sends from the live website. An unknown id answers 404, a name another goal of the site uses answers 409 taken, and an event goal may not use a name the tracker keeps for itself (400 invalid). Sending the same input twice leaves the goal as it is. Needs a token with the Write permission.

Input #

Output #

Example #

curl -s -X POST https://clearsaga.com/api/v1/goals.update \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","id":"GOAL_ID","type":"page","name":"Reached pricing","pathPattern":"/pricing"}'

clearsaga goals update --input '{"siteId":"site_abc123def456","id":"GOAL_ID","type":"page","name":"Reached pricing","pathPattern":"/pricing"}'

Tool: goals_update
Arguments: {"siteId":"site_abc123def456","id":"GOAL_ID","type":"page","name":"Reached pricing","pathPattern":"/pricing"}

Run clearsaga help goals update for one flag per field.