Performance
Page vitals at the 75th percentile, slow and failing API calls, the element behind each vital, click maps with rage and dead clicks, form failures, custom events and the weekly suggestions.
All numbers come from real visits. Percentiles are computed from fixed-bucket histograms, so they can be
merged across hours: a p75 is exact to its bucket, not to the millisecond. When a percentile lands beyond the
last bucket the row says so with an _overflow flag: the real value is above the number shown.
| Vital | Good | Poor | Unit |
|---|---|---|---|
| LCP, largest contentful paint | up to 2,500 | above 4,000 | ms |
| INP, interaction to next paint | up to 200 | above 500 | ms |
| CLS, cumulative layout shift | up to 0.1 | above 0.25 | score |
| TTFB, time to first byte | up to 800 | above 1,800 | ms |
Get the performance summary
/v1/performance EngineCloud The numbers for the whole app, and what got worse: the pages and API calls whose numbers moved the most
against the period just before, of the same length. It is what the MCP tool performance returns.
A page is listed in slower_pages when its LCP at the 75th percentile grew by 30 % or more and it had at least
50 views in both periods. An API call is listed in failing_api when more than 2 % of its requests answered
5xx or nothing, with at least 50 requests.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
sincestring optionalStart of the period. The comparison period is the same length, just before it.
Default:
7d -
untilstring optionalEnd of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
Request
curl "https://api.sypnia.com/v1/performance?since=24h" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"period": {
"since": "2026-03-11T10:35:00Z",
"until": "2026-03-12T10:35:00Z"
},
"vitals": {
"lcp_p75_ms": 2300,
"inp_p75_ms": 160,
"cls_p75": 0.03,
"ttfb_p75_ms": 380,
"poor_share": 0.12,
"page_loads": 4210
},
"slower_pages": [
{
"route": "/search",
"lcp_p75_ms": 3100,
"previous_lcp_p75_ms": 1900,
"views": 1840
}
],
"slowest_pages": [
{
"route": "/search",
"lcp_p75_ms": 3100,
"views": 1840
},
{
"route": "/products/:id",
"lcp_p75_ms": 2200,
"views": 1310
},
{
"route": "/checkout",
"lcp_p75_ms": 1400,
"views": 58
}
],
"failing_api": [],
"slowest_api": [
{
"method": "POST",
"route": "/api/checkout",
"p95_ms": 3900,
"requests": 36,
"error_rate": 0.139
}
],
"rage_click_pages": [
{
"route": "/checkout",
"rage_clicks": 1,
"views": 58
}
],
"suggestions": {
"new": 1
}
}List page performance
/v1/performance/pages EngineCloud One row per page route, with views, time spent, the four vitals at the 75th percentile, the share of page loads rated poor, and how many errors, rage clicks and dead clicks happened there. Each vital has its own sample count: a p75 from 3 samples is not a fact.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
sincestring optionalStart of the period.
Default:
7d -
untilstring optionalEnd of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
-
devicestring optionalOnly measurements from this kind of device. One of:
mobile,tablet,desktop. -
sortstring optionalWhich column to order by, worst or largest first. One of:
views,sessions,seconds,lcp,inp,cls,ttfb,poor,errors,rage,dead.Default:
views -
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://api.sypnia.com/v1/performance/pages?sort=lcp&since=24h" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"data": [
{
"route": "/search",
"views": 1840,
"sessions": 402,
"avg_seconds": 38.2,
"lcp_p75_ms": 3100,
"lcp_samples": 1612,
"lcp_overflow": false,
"inp_p75_ms": 180,
"inp_samples": 1204,
"inp_overflow": false,
"cls_p75": 0.04,
"ttfb_p75_ms": 410,
"poor_share": 0.21,
"errors": 0,
"rage_clicks": 2,
"dead_clicks": 9
},
{
"route": "/checkout",
"views": 58,
"sessions": 51,
"avg_seconds": 44.0,
"lcp_p75_ms": 1400,
"lcp_samples": 55,
"lcp_overflow": false,
"inp_p75_ms": 120,
"inp_samples": 49,
"inp_overflow": false,
"cls_p75": 0.01,
"ttfb_p75_ms": 320,
"poor_share": 0.02,
"errors": 5,
"rage_clicks": 1,
"dead_clicks": 0
}
],
"next_cursor": null
}List API call performance
/v1/performance/api EngineCloud One row per API route and method, seen from both sides: from the browser (how long the person waited, how many calls failed) and from the server (how long the handler took, how many downstream calls it made). Rows that only have server data come from backends that send traces without a browser SDK.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
sincestring optionalStart of the period.
Default:
7d -
untilstring optionalEnd of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
-
routestring, up to 500 characters optionalOnly this API route.
-
sortstring optionalrequests,error_rate,p95(browser),server_p95orcalls(downstream calls per request).Default:
requests -
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://api.sypnia.com/v1/performance/api?sort=error_rate&since=24h" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"data": [
{
"method": "POST",
"route": "/api/checkout",
"requests": 36,
"ok": 31,
"client_errors": 5,
"server_errors": 0,
"network_errors": 0,
"error_rate": 0.139,
"p50_ms": 900,
"p95_ms": 3900,
"server_requests": 36,
"server_p95_ms": 3850,
"avg_calls": 2.0,
"avg_calls_ms": 1210
}
],
"next_cursor": null
}Get the elements behind a page’s vitals
/v1/performance/vitals EngineCloud For one page, the elements that the browser blamed for each vital: the element that was the largest paint (LCP), the element whose interaction was slow (INP) and the element that moved the layout most (CLS). This is what turns «the search page is slow» into «the product grid’s first image is slow». Up to 10 elements per vital, most sampled first. TTFB has no element.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
routestring, up to 500 characters requiredThe page route, starting with
/. -
sincestring optionalStart of the period.
Default:
7d -
untilstring optionalEnd of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
-
devicestring optionalOnly measurements from this kind of device. One of:
mobile,tablet,desktop.
Request
curl "https://api.sypnia.com/v1/performance/vitals?route=/search&since=24h" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"route": "/search",
"device": null,
"lcp": [
{
"selector": "main ul.results > li:nth-child(1) img",
"kind": "image",
"samples": 1310,
"p75_ms": 3200,
"poor_share": 0.24
},
{
"selector": "main h1",
"kind": "text",
"samples": 302,
"p75_ms": 1300,
"poor_share": 0.01
}
],
"inp": [
{
"selector": "form.filters select#sort",
"kind": "pointer",
"samples": 640,
"p75_ms": 210,
"poor_share": 0.03
}
],
"cls": [
{
"selector": "aside.promo",
"kind": null,
"samples": 480,
"p75": 0.06,
"poor_share": 0.02
}
]
}Errors
- 400
invalid_requestrouteis missing or does not start with/.
Get a page’s click map
/v1/clicks EngineCloud Where people click on one page: the elements they clicked, most clicked first, with how many of those clicks
were rage clicks (the same spot again and again) and dead clicks (a click that changed nothing). Rows
of a list that share one control are joined into one element (instances). Each element has sample sessions
to watch.
label is what the control says («Pay $64.00»). It is only stored when most clicks on that element showed
the same text; for list rows and links to one record it is null, because that text would be a person’s
name or an order number.
To find which pages to look at, list page performance sorted by rage or dead. To draw the map over the
page, get the page snapshot.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
routestring, up to 500 characters requiredThe page route, starting with
/. -
devicestring optionalLayouts differ by device, so a click map is always for one. One of:
mobile,tablet,desktop.Default:
desktop -
sincestring optionalStart of the period.
Default:
7d -
untilstring optionalEnd of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
-
onlystring optionalrageordeadreturns only elements with such clicks. -
limitinteger, 1 to 200 optionalMost elements to return.
Default:
50
Request
curl "https://api.sypnia.com/v1/clicks?route=/checkout&only=rage" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"route": "/checkout",
"device": "desktop",
"totals": {
"clicks": 214,
"rage_clicks": 1,
"dead_clicks": 0,
"elements": 17
},
"elements": [
{
"selector": "#pay-button",
"role": "button",
"label": "Pay $64.00",
"context": "Your order",
"clicks": 41,
"rage_clicks": 1,
"dead_clicks": 0,
"share": 0.19,
"instances": 1,
"box": {
"x": 880,
"y": 612,
"width": 240,
"height": 48
},
"sample_sessions": [
"8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0"
]
}
]
}Errors
- 400
invalid_requestrouteis missing or does not start with/.
Get a page snapshot
/v1/clicks/snapshot EngineCloud A snapshot of the page to draw a click map over: the fullest of the ten most recent ones for the route and
device, as a link that works for 15 minutes. The snapshot is an rrweb snapshot, masked like a replay, so it
needs the replay scope. When the device you asked for has none, the nearest device’s snapshot is returned
and device_used says which.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
routestring, up to 500 characters requiredThe page route, starting with
/. -
devicestring optionalThe device layout you want. One of:
mobile,tablet,desktop.Default:
desktop -
taken_attimestamp optionalReturn this exact snapshot, one of
candidates, instead of the fullest.
Request
curl "https://api.sypnia.com/v1/clicks/snapshot?route=/checkout" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"found": true,
"route": "/checkout",
"device_requested": "desktop",
"device_used": "desktop",
"taken_at": "2026-03-12T10:31:30Z",
"viewport": {
"width": 1440,
"height": 900
},
"page_height": 1630,
"mask": 1,
"url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/snapshots/…?X-Amz-Signature=…",
"expires_at": "2026-03-12T10:55:00Z",
"candidates": [
{
"taken_at": "2026-03-12T10:31:30Z",
"device": "desktop"
},
{
"taken_at": "2026-03-12T09:02:55Z",
"device": "desktop"
}
]
}Errors
- 403
forbiddenThe token does not have the
replayscope.
List form failures
/v1/form-failures EngineCloud Forms that people could not send because the browser’s own validation stopped them: a required field left empty, an e-mail in the wrong shape. One row per page, field and reason. The field is named by its label, never by what was typed. People rarely report these; they just leave.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
sincestring optionalStart of the period.
Default:
7d -
untilstring optionalEnd of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
-
routestring, up to 500 characters optionalOnly this page.
-
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://api.sypnia.com/v1/form-failures?since=7d" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"data": [
{
"route": "/checkout",
"field": "Postal code",
"context": "Shipping address",
"reason": "patternMismatch",
"count": 12,
"sessions": 9,
"sample_sessions": [
"2b7d9e4f1a6c4830b5d2f7e9c1a3b5d7"
]
}
],
"next_cursor": null
}List the weekly suggestions
/v1/suggestions EngineCloud Once a week the agent looks at the week’s numbers and proposes improvements to performance and to how the app
is used: a slow page and the element behind it, a button people rage-click, an API call that makes too many
database calls. Each suggestion comes with its evidence. Some are plain rules (INP above 500 ms at p75, more
than 3 rage clicks per 100 views, 5xx above 2 %) and are produced even without an AI provider; the ones that
need a model are skipped when the agent is off.
The run happens on Monday, 07:00 UTC, over the week that ended. last_run says when it last ran and how.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
environmentstring optionalThe environment to read. Any name the project has sent, or
all.Default:
production -
statusstring optionalWhich suggestions to return. One of:
new,accepted,dismissed,done,all.Default:
new -
categorystring optionalOnly this kind. One of:
performance,usability,reliability. -
sincestring optionalOnly suggestions from weeks that started after this moment.
Default:
56d -
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://api.sypnia.com/v1/suggestions" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"data": [
{
"id": "sug_3h7j1k5l9p2o",
"week": "2026-03-02",
"category": "performance",
"status": "new",
"title": "The search page's first product image loads slowly",
"text": "Three of four visits wait more than 3 seconds for the search page to show its main content. The element is the first product image. Serve it smaller, or load it before the rest.",
"route": "/search",
"rule": "lcp_p75",
"evidence": [
"LCP at p75 is 3,100 ms over 1,612 page loads; it was 1,900 ms the week before.",
"In 81 % of slow loads the LCP element is `main ul.results > li:nth-child(1) img`."
],
"created_at": "2026-03-09T07:02:14Z"
}
],
"counts": {
"new": 1,
"accepted": 2,
"dismissed": 1,
"done": 3
},
"last_run": {
"week": "2026-03-02",
"status": "ok",
"suggestions": 1,
"model_used": true
},
"next_cursor": null
}Set a suggestion’s status
/v1/suggestions/{suggestion_id} EngineCloud Marks a suggestion as accepted, dismissed or done, or back to new. A dismissed suggestion is not proposed again for 8 weeks.
Path parameters
-
suggestion_idstring requiredThe suggestion’s id (
sug_…).
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Body
-
statusstring requiredThe new status. One of:
new,accepted,dismissed,done.
Request
curl -X PATCH "https://api.sypnia.com/v1/suggestions/sug_3h7j1k5l9p2o" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status": "accepted"}'Response200
{
"id": "sug_3h7j1k5l9p2o",
"week": "2026-03-02",
"category": "performance",
"status": "accepted",
"title": "The search page's first product image loads slowly",
"text": "Three of four visits wait more than 3 seconds for the search page to show its main content. The element is the first product image. Serve it smaller, or load it before the rest.",
"route": "/search",
"rule": "lcp_p75",
"evidence": [
"LCP at p75 is 3,100 ms over 1,612 page loads; it was 1,900 ms the week before.",
"In 81 % of slow loads the LCP element is `main ul.results > li:nth-child(1) img`."
],
"created_at": "2026-03-09T07:02:14Z"
}Errors
- 404
not_foundNo suggestion has this id in the project.
The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.