Skip to content

API reference Usage

API reference

Usage

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

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

Usage this month #

POST /api/v1/usage.get · Read

How many events the workspace recorded in one UTC month, per site and in total, next to the plan's monthly allowance (quota). An event is a page view or a custom event. Leave month out for the current month. locked says whether the dashboards are locked because the allowance was reached; while they are, report operations answer 402 workspace_locked but this one keeps working, so a program can learn why. Visits are still counted under that lock, up to the safety ceiling in breakerEvents. Nothing here is a price.

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

Input #

Field Type Required Description
month string optional The UTC month to report, YYYY-MM. Left out, the current month.

Output #

Field Type Present Description
period string always The UTC month the numbers are for, YYYY-MM.
quota number always The plan's monthly event allowance, for all sites of the workspace together.
sites array of object always Events recorded per site in the month, most first. Every site is listed, also with zero. A site deleted during the month keeps its row, because its events still count.
total number always Events recorded in the month across all sites. Compare it with quota.
locked boolean always True when the dashboards are locked for the rest of the month because the allowance was reached. Visits are still being counted.
lockedUntil number | null always When that lock lifts by itself (the first of next month, UTC) in milliseconds since 1970 UTC. Null when not locked.
warnAtPct number always The share of the allowance, in percent, at which the workspace owner is warned by email.
breakerEvents number always The safety ceiling: the number of events in a month at which collection pauses until the next month or a larger plan.

Example #

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

Run clearsaga help usage get for one flag per field.