# 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: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/performance/

For agents: Reference of the Performance endpoints of the Sypnia HTTP API: parameters, response shapes, examples and errors.

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

`GET /v1/performance` \[Engine, Cloud]

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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `7d`): Start of the period. The comparison period is the same length, just before it.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

**Request:**

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

**Response (200):**

```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` \[Engine, Cloud]

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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `7d`): Start of the period.
- `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, default `views`): Which column to order by, worst or largest first. One of: `views`, `sessions`, `seconds`, `lcp`, `inp`, `cls`, `ttfb`, `poor`, `errors`, `rage`, `dead`.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

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

**Response (200):**

```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` \[Engine, Cloud]

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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `7d`): Start of the period.
- `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, default `requests`): `requests`, `error_rate`, `p95` (browser), `server_p95` or `calls` (downstream calls per request).
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

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

**Response (200):**

```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` \[Engine, Cloud]

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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `route` (string, up to 500 characters, required): The page route, starting with `/`.
- `since` (string, optional, default `7d`): Start of the period.
- `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:**

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

**Response (200):**

```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:**

- `400` `invalid_request`: `route` is missing or does not start with `/`.

## Get a page's click map

`GET /v1/clicks` \[Engine, Cloud]

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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `route` (string, up to 500 characters, required): The page route, starting with `/`.
- `device` (string, optional, default `desktop`): Layouts differ by device, so a click map is always for one. One of: `mobile`, `tablet`, `desktop`.
- `since` (string, optional, default `7d`): Start of the period.
- `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, default `50`): Most elements to return.

**Request:**

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

**Response (200):**

```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:**

- `400` `invalid_request`: `route` is missing or does not start with `/`.

## Get a page snapshot

`GET /v1/clicks/snapshot` \[Engine, Cloud]

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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `route` (string, up to 500 characters, required): The page route, starting with `/`.
- `device` (string, optional, default `desktop`): The device layout you want. One of: `mobile`, `tablet`, `desktop`.
- `taken_at` (timestamp, optional): Return this exact snapshot, one of `candidates`, instead of the fullest.

**Request:**

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

**Response (200):**

```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:**

- `403` `forbidden`: The token does not have the `replay` scope.

## List form failures

`GET /v1/form-failures` \[Engine, Cloud]

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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `7d`): Start of the period.
- `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, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

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

**Response (200):**

```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` \[Engine, Cloud]

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, default `production`): The environment to read. Any name the project has sent, or `all`.
- `status` (string, optional, default `new`): Which suggestions to return. One of: `new`, `accepted`, `dismissed`, `done`, `all`.
- `category` (string, optional): Only this kind. One of: `performance`, `usability`, `reliability`.
- `since` (string, optional, default `56d`): Only suggestions from weeks that started after this moment.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

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

**Response (200):**

```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}` \[Engine, Cloud]

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:**

```bash
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"}'
```

**Response (200):**

```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:**

- `404` `not_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](https://docs.sypnia.com/api/errors-limits-pagination).
