Skip to content

API reference Performance

API reference

Performance

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

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

Web vitals report #

POST /api/v1/performance.report · Read

How fast one site loads and responds for real visitors in a period, from the web vitals their browsers measured: lcp (largest contentful paint), inp (interaction to next paint), cls (cumulative layout shift), fcp (first contentful paint) and ttfb (time to first byte). Get the siteId from sites.list first. The answer has a tile for all five metrics, and for the one named in metric a chart over time, the ten slowest pages and the split by browser, device and country. p75 is the value that 75 percent of the measurements were at or below, and status judges it against the public Core Web Vitals bands: good, needs_improvement or poor. lcp, inp, fcp and ttfb are milliseconds; cls is a score. A site only has samples when vitals collection is on; sites.get says so in hasVitals, and without samples the tiles have status none. A sample belongs to no visit, so only the page, hostname, country, browser, system and device filters apply; any other filter that was sent is left out and listed in ignoredFilters, once by its plain key (ref for ref.has). 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 #

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.
metric "lcp" | "inp" | "cls" | "fcp" | "ttfb" required The metric the chart, the slowest pages and the breakdowns are for: lcp, inp, cls, fcp or ttfb. The tiles always cover all five.

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 in the same form, or null when there is none.
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.
metric "lcp" | "inp" | "cls" | "fcp" | "ttfb" always The metric the chart, the pages and the breakdowns are for.
tiles array of object always One row per metric, all five whatever metric was asked for: p50, p75 and p95 (the value that 50, 75 and 95 percent of the measurements were at or below), the number of samples, and status, which is judged on the p75: good, needs_improvement, poor, or none without samples. lcp, inp, fcp and ttfb are milliseconds; cls is a score without a unit. compare holds the p75 of the comparison period and delta, the change as a fraction (0.1 means 10 percent slower); it is null without a comparison.
points array of object always The chart of the chosen metric: one point per bucket of the period, oldest first, with start and end in milliseconds since 1970 UTC (end exclusive), the three percentiles (null for a bucket without samples) and the number of samples.
pages array of object always The ten slowest pages for the chosen metric, highest p75 first. Only pages with at least 3 samples are listed.
breakdowns object always The chosen metric by browser, by device and by country: for each, rows (the ten most measured values with key, label, p75, samples and status) and total, the number of distinct values.
subsetK number always 1 when every sample was read. A larger number k means the period held so many samples that every k-th one was used, so percentiles are close estimates.
ignoredFilters array of string always Filter keys of the input that a performance sample cannot carry and that were left out. Only the page, hostname, country, browser, system and device filters apply. A filter is named once by its plain key, whichever form was sent: ref.has and ref.not are both listed as ref.

Example #

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

Run clearsaga help performance report for one flag per field.