> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Vitals API

> Query aggregate, timeline, URL-level, and breakdown Web Vitals data.

Use the Web Vitals API to understand frontend performance by environment, URL, page segment, geography, browser, device, campaign, user, trace, and metric.

## Operations

| Operation          | Method and path                                  | Purpose                                                                                                        |
| ------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `vitals.summary`   | `GET /v1/projects/{project_id}/vitals`           | Aggregate p50, p75, p90, p95, p99, and rating distribution.                                                    |
| `vitals.timeline`  | `GET /v1/projects/{project_id}/vitals/timeline`  | Time-series data for charting one metric and percentile.                                                       |
| `vitals.urls`      | `GET /v1/projects/{project_id}/vitals/urls`      | Per-URL breakdown for slowest pages.                                                                           |
| `vitals.breakdown` | `GET /v1/projects/{project_id}/vitals/breakdown` | Segment one metric by page, country, region, city, browser, device, campaign, user, trace, and related fields. |

Common filters include `environment`, `metric`, `period`, `url`, `rating`, `limit`, timeline `granularity` of `1h`, `6h`, or `1d`, and `percentile` values `p50`, `p75`, `p90`, `p95`, or `p99`.

Supported Web Vitals filter fields are `page_path`, `query_string`, `referrer`, `country`, `region`, `city`, `timezone`, `language`, `device_type`, `browser`, `os`, `utm_source`, `utm_medium`, `utm_campaign`, `provider`, `model`, `call_type`, `finish_reason`, `error_name`, `http_status`, `user_id`, `trace_id`, `route`, and `connection`.

Breakdown rows include the selected `dimension` value and may include a `country` code when segmenting by region or city, so clients can label geographic rows without a second lookup.

## CLI and MCP

Use `squasher vitals list`, `squasher vitals summary`, `squasher vitals detail`, or `squasher vitals breakdown --project <project_id> --metric LCP --dimension page_path --percentile p75 --period 24h` for terminal workflows. Add repeatable filters with `--filter field=value`, for example `--filter page_path=/pricing --filter country=US`.

In MCP Code Mode, call `search("vitals")` before executing. Prefer `vitals.summary` for a fast project overview, then `vitals.breakdown` when an agent needs to compare pages, countries, regions, cities, browsers, device types, campaigns, users, or traces.

## Agent handoff

```text theme={null}
Analyze Squasher Web Vitals for project <project_id>. Start with vitals.summary for the target metric and period, then use vitals.timeline, vitals.urls, or vitals.breakdown only when needed. Return metric, percentile, rating, segment, URL, environment, and period for every finding.
```

Related: [Browser SDK](/sdks/browser), [Next.js SDK](/sdks/nextjs).