Overview reports

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

Filtered bot traffic #

POST /api/v1/overview.bots · Read

How many requests to one site were recognised as automated and left out of every other number, by reason (crawlers, scripts, automated browsers, referrer spam, datacenter networks and so on), next to the requests that were recorded. Get the siteId from sites.list first. These are requests, not visitors, and they are counted per whole UTC hour, so the period is widened to whole hours; the answer says which in hours. It takes no filters, because a filtered request has nothing to filter by, and it has no comparison: compare, cfrom and cto are accepted and ignored. share and shareOfRequests are fractions from 0 to 1 of filtered plus recorded requests. 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/overview.bots \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga overview bots --input '{"siteId":"site_abc123def456"}'

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

Run clearsaga help overview bots for one flag per field.

Breakdown by dimension #

POST /api/v1/overview.breakdown · Read

One breakdown list of a site for a period: the top values of a dimension with their visitors, visits, share and credited revenue. 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. It pages by offset: limit rows (8 unless set, 100 at most) starting at offset, and totalRows is the number of rows there are. Only the first 1000 rows can be reached, so offset plus limit may not be more than 1000 (400 otherwise). Rows are sorted by visitors, most first, unless sort and dir say otherwise; search keeps the rows whose label contains the text. share is the row's visitors divided by scopeVisitors, a fraction from 0 to 1. On page and hostname dimensions one visitor can be in several rows, so shares add up to more than 1. Visits without a value are left out of referrer, ai_tool, region and city (omittedVisitors counts their visitors) and are one row with an empty key elsewhere. revenue is the revenue credited to the row in minor units (cents), or null; exit_page never has any. The key of a row is the value the matching filter takes when filterable is true. Every filter applies; with a conversion filter each row also carries baseVisitors and conversionRate. The comparison is not used. 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/overview.breakdown \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456","dimension":"page"}'

clearsaga overview breakdown --input '{"siteId":"site_abc123def456","dimension":"page"}'

Tool: overview_breakdown
Arguments: {"siteId":"site_abc123def456","dimension":"page"}

Run clearsaga help overview breakdown for one flag per field.

Conversions by hour #

POST /api/v1/overview.conversionPeak · Read

When conversions happen: a grid of 7 weekdays by 24 hours in the site's time zone with the number of conversions in each cell, and their total. Row 0 is Monday. Get the siteId from sites.list first. A conversion is a completion of an enabled conversion goal (mode goals). A site without an enabled goal counts every custom event instead (mode events). With a conversion filter only the completions of that goal are counted. The other filters apply as everywhere. There is no comparison: compare, cfrom and cto change nothing in the numbers. 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/overview.conversionPeak \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga overview conversionPeak --input '{"siteId":"site_abc123def456"}'

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

Run clearsaga help overview conversionPeak for one flag per field.

Headline numbers #

POST /api/v1/overview.kpis · Read

The headline numbers of one site for a period: visitors, visits, page views, bounce rate, average session time, conversion rate, revenue and revenue per visitor. It answers the same numbers for the comparison period (previous) and the change between the two (delta). Get the siteId from sites.list first. A visitor is counted once per day, so visitors over several days is the sum of the daily counts. Rates are fractions from 0 to 1 and session time is in seconds. Money is in minor units (cents) of revenue.currency; amounts in other currencies are listed in revenue.otherCurrencies and never added in. conversionRate is the share of visitors who completed any enabled conversion goal on the day of their visit; it is null when the site has no enabled goal. revenue and revenuePerVisitor are null when the site never recorded an order. Without filters revenue is net of refunds; with filters it is the gross revenue credited to the matching visits. With a conversion filter, visitors are the visitors who completed that goal and conversion gives their share of all visitors. previous and delta are null when compare is off or the range is all. 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/overview.kpis \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga overview kpis --input '{"siteId":"site_abc123def456"}'

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

Run clearsaga help overview kpis for one flag per field.

Pages not found #

POST /api/v1/overview.missingPages · Read

The paths of one site that answered "not found" in a period, most hits first, each with the page that most often linked to it. Get the siteId from sites.list first. A site only has these when its tracker reports missing pages; sites.get says so in has404Tracking. It pages by offset: limit rows (8 unless set, 100 at most) starting at offset, and totalRows is the number of paths there are; offset plus limit may not be more than 1000. search keeps the paths that contain the text. A hit on a missing page is not a page view, so the path, event, prop and conversion filters are ignored here; the hostname filter and the filters about the visit (source, place, device, campaign tags) apply. The comparison is not used. 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/overview.missingPages \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga overview missingPages --input '{"siteId":"site_abc123def456"}'

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

Run clearsaga help overview missingPages for one flag per field.

Traffic over time #

POST /api/v1/overview.timeseries · Read

The main chart of one site: visitors, visits, page views, bounce rate, session time, revenue, orders and goal converters per bucket of the period, and the same for the comparison period. Get the siteId from sites.list first. The bucket size follows the period and is named in window.granularity: minutes for 30m, hours up to two days, days up to about three months, then weeks or months. compareBuckets lines up with buckets by position, not by time, and is null when compare is off or the range is all. A visitor who is active in two buckets is counted in both, so with buckets shorter than a day the visitors of the buckets add up to more than the visitors of overview.kpis. Rates are fractions from 0 to 1 and session time is in seconds. revenue per bucket is in minor units (cents) of the currency overview.kpis names: the money taken in the bucket without filters, the revenue credited to the matching visits with them, and null when the site never had an order. Every filter applies. 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/overview.timeseries \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

clearsaga overview timeseries --input '{"siteId":"site_abc123def456"}'

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

Run clearsaga help overview timeseries for one flag per field.