Skip to main content
GET
/
web_vitals_routes
Web Vitals Routes
curl --request GET \
  --url https://api.example.com/web_vitals_routes
{
  "route": "<string>",
  "full_pathname": "<string>",
  "route_part": "<string>",
  "overall_score": 123,
  "lcp_avg": 123,
  "ttfb_avg": 123,
  "fcp_avg": 123,
  "inp_avg": 123,
  "cls_avg": 123,
  "lcp_score": 123,
  "ttfb_score": 123,
  "fcp_score": 123,
  "inp_score": 123,
  "cls_score": 123,
  "metric_units": "<string>",
  "domain": "<string>",
  "analysis_type": "<string>"
}
Returns web vitals metrics aggregated by route or pathname, allowing you to identify which pages on your site have the best or worst performance. Supports pagination and flexible sorting.

​
Endpoint

GET https://api.tinybird.co/v0/pipes/web_vitals_routes.json

​
Parameters

​
days
integer
default:"1"
Number of days to analyze. Defaults to 1 day (last 24 hours).
​
tenant_id
string
Filter results by tenant ID for multi-tenant applications.
​
domain
string
Filter results by domain name (e.g., “example.com”).
​
route
string
Filter to a specific route (e.g., “home”, “products”, “checkout”).
​
analysis_type
string
Analysis granularity:
  • “routes” (default): Group by route (e.g., /products/:id becomes “products”)
  • “pathnames”: Group by exact pathname (e.g., /products/123, /products/456 are separate)
​
sort_order
string
Sort order for results:
  • “asc” (default): Best performing routes first (highest scores)
  • “desc”: Worst performing routes first (lowest scores)
​
skip
integer
default:"0"
Number of records to skip for pagination. Defaults to 0.
​
limit
integer
default:"10"
Maximum number of records to return. Defaults to 10, useful for pagination.

​
Web Vitals Metrics Tracked

This endpoint aggregates all five Core Web Vitals metrics by route:

​
LCP (Largest Contentful Paint)

Loading performance - measures how quickly the main content loads.
  • Excellent: ≤2500ms
  • Good: ≤4000ms
  • Poor: >4000ms

​
TTFB (Time to First Byte)

Server response time - measures backend performance.
  • Excellent: ≤500ms
  • Good: ≤1000ms
  • Poor: >1000ms

​
FCP (First Contentful Paint)

Time until first content - measures perceived load speed.
  • Excellent: ≤1800ms
  • Good: ≤3000ms
  • Poor: >3000ms

​
INP (Interaction to Next Paint)

Responsiveness - measures how quickly the page responds to interactions.
  • Excellent: ≤200ms
  • Good: ≤500ms
  • Poor: >500ms

​
CLS (Cumulative Layout Shift)

Visual stability - measures unexpected layout shifts.
  • Excellent: ≤0.1
  • Good: ≤0.25
  • Poor: >0.25

​
Response Fields

​
route
string
The route identifier (when analysis_type=“routes”) or pathname (when analysis_type=“pathnames”).
​
full_pathname
string
Only present when analysis_type=“pathnames”. The complete pathname analyzed.
​
route_part
string
Only present when analysis_type=“pathnames”. The route portion extracted from the pathname.
​
overall_score
float
Composite performance score across all metrics, from 0-100. Higher is better.
​
lcp_avg
float
Average Largest Contentful Paint in milliseconds. Null if no measurements.
​
ttfb_avg
float
Average Time to First Byte in milliseconds. Null if no measurements.
​
fcp_avg
float
Average First Contentful Paint in milliseconds. Null if no measurements.
​
inp_avg
float
Average Interaction to Next Paint in milliseconds. Null if no measurements.
​
cls_avg
float
Average Cumulative Layout Shift score (0-1). Null if no measurements.
​
lcp_score
float
Performance score for LCP (0-100). Null if no measurements.
​
ttfb_score
float
Performance score for TTFB (0-100). Null if no measurements.
​
fcp_score
float
Performance score for FCP (0-100). Null if no measurements.
​
inp_score
float
Performance score for INP (0-100). Null if no measurements.
​
cls_score
float
Performance score for CLS (0-100). Null if no measurements.
​
metric_units
string
Description of units for each metric: “LCP=ms, TTFB=ms, FCP=ms, INP=ms, CLS=score”.
​
domain
string
The domain this data was collected from.
​
analysis_type
string
The type of analysis performed: “routes” or “pathnames”.

​
Example Request

​
Get Worst Performing Routes

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.tinybird.co/v0/pipes/web_vitals_routes.json?days=7&sort_order=desc&limit=5"

​
Get Specific Route Performance

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.tinybird.co/v0/pipes/web_vitals_routes.json?route=checkout&days=30"

​
Analyze Individual Pathnames

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.tinybird.co/v0/pipes/web_vitals_routes.json?analysis_type=pathnames&days=7&limit=20"

​
Example Response

{
  "data": [
    {
      "route": "home",
      "overall_score": 92.5,
      "lcp_avg": 2100.34,
      "ttfb_avg": 345.67,
      "fcp_avg": 1650.89,
      "inp_avg": 180.23,
      "cls_avg": 0.08,
      "lcp_score": 100,
      "ttfb_score": 100,
      "fcp_score": 100,
      "inp_score": 100,
      "cls_score": 100,
      "metric_units": "LCP=ms, TTFB=ms, FCP=ms, INP=ms, CLS=score",
      "domain": "example.com",
      "analysis_type": "routes"
    },
    {
      "route": "products",
      "overall_score": 78.3,
      "lcp_avg": 3234.56,
      "ttfb_avg": 567.89,
      "fcp_avg": 2345.67,
      "inp_avg": 234.56,
      "cls_avg": 0.15,
      "lcp_score": 75,
      "ttfb_score": 75,
      "fcp_score": 75,
      "inp_score": 100,
      "cls_score": 75,
      "metric_units": "LCP=ms, TTFB=ms, FCP=ms, INP=ms, CLS=score",
      "domain": "example.com",
      "analysis_type": "routes"
    },
    {
      "route": "checkout",
      "overall_score": 45.8,
      "lcp_avg": 5678.90,
      "ttfb_avg": 1234.56,
      "fcp_avg": 4567.89,
      "inp_avg": 678.90,
      "cls_avg": 0.32,
      "lcp_score": 25,
      "ttfb_score": 25,
      "fcp_score": 25,
      "inp_score": 25,
      "cls_score": 25,
      "metric_units": "LCP=ms, TTFB=ms, FCP=ms, INP=ms, CLS=score",
      "domain": "example.com",
      "analysis_type": "routes"
    }
  ]
}

​
Use Cases

  • Performance Prioritization: Identify which routes need optimization most urgently
  • A/B Testing: Compare performance between different page implementations
  • Route-Specific Optimization: Focus optimization efforts on specific problematic routes
  • Performance Monitoring: Track how individual routes perform over time
  • Resource Allocation: Determine which pages impact user experience most
  • Checkout Funnel Analysis: Monitor performance of critical conversion paths

​
Notes

  • Routes require at least 3 measurements to appear in results (to ensure statistical significance)
  • The overall_score is calculated as the average of all available metric scores
  • When using analysis_type="pathnames", you get more granular data but may have lower sample sizes per pathname
  • Use pagination (skip and limit) for large result sets to improve performance

Build docs developers (and LLMs) love

Get started for freeTalk to us