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>"
}

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tinybirdco/web-analytics-starter-kit/llms.txt

Use this file to discover all available pages before exploring further.

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