Docs

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.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Get the performance summary
  2. List page performance
  3. List API call performance
  4. Get the elements behind a page’s vitals
  5. Get a page’s click map
  6. Get a page snapshot
  7. List form failures
  8. List the weekly suggestions
  9. Set a suggestion’s status

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.

VitalGoodPoorUnit
LCP, largest contentful paintup to 2,500above 4,000ms
INP, interaction to next paintup to 200above 500ms
CLS, cumulative layout shiftup to 0.1above 0.25score
TTFB, time to first byteup to 800above 1,800ms

Get the performance summary

GET /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.

Authentication
API token (read)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Start of the period. The comparison period is the same length, just before it.

    Default: 7d

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

Request

Terminal
curl "https://api.sypnia.com/v1/performance?since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

GET /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.

Authentication
API token (read)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Start of the period.

    Default: 7d

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

  • device
    string optional

    Only measurements from this kind of device. One of: mobile, tablet, desktop.

  • sort
    string optional

    Which column to order by, worst or largest first. One of: views, sessions, seconds, lcp, inp, cls, ttfb, poor, errors, rage, dead.

    Default: views

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

Terminal
curl "https://api.sypnia.com/v1/performance/pages?sort=lcp&since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

GET /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.

Authentication
API token (read)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Start of the period.

    Default: 7d

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

  • route
    string, up to 500 characters optional

    Only this API route.

  • sort
    string optional

    requests, error_rate, p95 (browser), server_p95 or calls (downstream calls per request).

    Default: requests

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

Terminal
curl "https://api.sypnia.com/v1/performance/api?sort=error_rate&since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

GET /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.

Authentication
API token (read)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • route
    string, up to 500 characters required

    The page route, starting with /.

  • since
    string optional

    Start of the period.

    Default: 7d

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

  • device
    string optional

    Only measurements from this kind of device. One of: mobile, tablet, desktop.

Request

Terminal
curl "https://api.sypnia.com/v1/performance/vitals?route=/search&since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

  • 400invalid_request

    route is missing or does not start with /.

Get a page’s click map

GET /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.

Authentication
API token (read)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • route
    string, up to 500 characters required

    The page route, starting with /.

  • device
    string optional

    Layouts differ by device, so a click map is always for one. One of: mobile, tablet, desktop.

    Default: desktop

  • since
    string optional

    Start of the period.

    Default: 7d

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

  • only
    string optional

    rage or dead returns only elements with such clicks.

  • limit
    integer, 1 to 200 optional

    Most elements to return.

    Default: 50

Request

Terminal
curl "https://api.sypnia.com/v1/clicks?route=/checkout&only=rage" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

  • 400invalid_request

    route is missing or does not start with /.

Get a page snapshot

GET /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.

Authentication
API token (replay)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • route
    string, up to 500 characters required

    The page route, starting with /.

  • device
    string optional

    The device layout you want. One of: mobile, tablet, desktop.

    Default: desktop

  • taken_at
    timestamp optional

    Return this exact snapshot, one of candidates, instead of the fullest.

Request

Terminal
curl "https://api.sypnia.com/v1/clicks/snapshot?route=/checkout" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

  • 403forbidden

    The token does not have the replay scope.

List form failures

GET /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.

Authentication
API token (read)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Start of the period.

    Default: 7d

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

  • route
    string, up to 500 characters optional

    Only this page.

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

Terminal
curl "https://api.sypnia.com/v1/form-failures?since=7d" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

GET /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.

Authentication
API token (read)

Query parameters

  • project
    string optional

    The 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.

  • environment
    string optional

    The environment to read. Any name the project has sent, or all.

    Default: production

  • status
    string optional

    Which suggestions to return. One of: new, accepted, dismissed, done, all.

    Default: new

  • category
    string optional

    Only this kind. One of: performance, usability, reliability.

  • since
    string optional

    Only suggestions from weeks that started after this moment.

    Default: 56d

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

Terminal
curl "https://api.sypnia.com/v1/suggestions" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Response200

JSON
{
  "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

PATCH /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.

Authentication
API token (read)

Path parameters

  • suggestion_id
    string required

    The suggestion’s id (sug_…).

Query parameters

  • project
    string optional

    The 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

  • status
    string required

    The new status. One of: new, accepted, dismissed, done.

Request

Terminal
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

JSON
{
  "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

  • 404not_found

    No suggestion has this id in the project.

The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close