Skip to main content
GET
/
web_vitals_distribution
Web Vitals Distribution
curl --request GET \
  --url https://api.example.com/web_vitals_distribution
{
  "metric_name": "<string>",
  "performance_category": "<string>",
  "avg_value": 123,
  "p75": 123,
  "p90": 123,
  "p95": 123,
  "p99": 123,
  "measurement_count": 123,
  "percentage": 123,
  "total_measurements": 123,
  "score": 123,
  "units": "<string>",
  "thresholds": "<string>",
  "description": "<string>",
  "domain": "<string>",
  "previous_avg_value": 123,
  "previous_p75": 123,
  "previous_p90": 123,
  "previous_p95": 123,
  "previous_p99": 123,
  "previous_measurement_count": 123,
  "previous_total_measurements": 123,
  "previous_percentage": 123,
  "avg_value_growth_percentage": 123,
  "measurement_count_growth_percentage": 123
}
Returns the distribution of web vitals measurements across performance categories (excellent, good, poor) with percentages and statistical metrics. Optionally includes previous period data for growth analysis.

​
Endpoint

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

​
Parameters

​
date_from
string
Start date for the analysis period (YYYY-MM-DD format). If not provided, defaults to yesterday.
​
date_to
string
End date for the analysis period (YYYY-MM-DD format). If not provided, defaults to today.
​
tenant_id
string
Filter results by tenant ID for multi-tenant applications.
​
domain
string
Filter results by domain name (e.g., “example.com”).
​
include_previous_period
string
Set to “true” to include previous period metrics and growth percentages. The previous period will be calculated automatically based on the length of the current period.

​
Web Vitals Metrics Tracked

This endpoint tracks all five Core Web Vitals metrics and categorizes each measurement:

​
Performance Categories

Each measurement is categorized into one of three performance buckets:
  • Excellent: Meets or exceeds the excellent threshold
  • Good: Between excellent and good thresholds
  • Poor: Exceeds the good threshold

​
Metric Thresholds

LCP (Largest Contentful Paint)
  • Excellent: ≤2500ms
  • Good: ≤4000ms
  • Poor: >4000ms
TTFB (Time to First Byte)
  • Excellent: ≤500ms
  • Good: ≤1000ms
  • Poor: >1000ms
FCP (First Contentful Paint)
  • Excellent: ≤1800ms
  • Good: ≤3000ms
  • Poor: >3000ms
INP (Interaction to Next Paint)
  • Excellent: ≤200ms
  • Good: ≤500ms
  • Poor: >500ms
CLS (Cumulative Layout Shift)
  • Excellent: ≤0.1
  • Good: ≤0.25
  • Poor: >0.25

​
Response Fields

​
metric_name
string
The name of the web vitals metric (LCP, TTFB, FCP, INP, or CLS).
​
performance_category
string
The performance category: “excellent”, “good”, or “poor”.
​
avg_value
float
Average value for this metric within this performance category.
​
p75
float
75th percentile value for this category.
​
p90
float
90th percentile value for this category.
​
p95
float
95th percentile value for this category.
​
p99
float
99th percentile value for this category.
​
measurement_count
integer
Number of measurements in this category.
​
percentage
float
Percentage of total measurements for this metric that fall into this category.
​
total_measurements
integer
Total number of measurements for this metric across all categories.
​
score
integer
Performance score for this category (100 for excellent, 75 for good, 25 for poor).
​
units
string
Units for the metric value (“ms” or “score”).
​
thresholds
string
Text description of the performance thresholds.
​
description
string
Description of what the metric measures.
​
domain
string
The domain this data was collected from.

​
Previous Period Fields (when include_previous_period=“true”)

​
previous_avg_value
float
Average value for this category in the previous period.
​
previous_p75
float
75th percentile value in the previous period.
​
previous_p90
float
90th percentile value in the previous period.
​
previous_p95
float
95th percentile value in the previous period.
​
previous_p99
float
99th percentile value in the previous period.
​
previous_measurement_count
integer
Number of measurements in the previous period.
​
previous_total_measurements
integer
Total measurements for this metric in the previous period.
​
previous_percentage
float
Percentage of measurements in this category during the previous period.
​
avg_value_growth_percentage
float
Percentage change in average value compared to previous period. Negative is better for timing metrics.
​
measurement_count_growth_percentage
float
Percentage change in measurement count compared to previous period.

​
Example Request

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.tinybird.co/v0/pipes/web_vitals_distribution.json?date_from=2024-01-01&date_to=2024-01-07&include_previous_period=true"

​
Example Response

{
  "data": [
    {
      "metric_name": "LCP",
      "performance_category": "excellent",
      "avg_value": 1850.23,
      "p75": 2100.45,
      "p90": 2350.67,
      "p95": 2450.89,
      "p99": 2499.12,
      "measurement_count": 8532,
      "percentage": 68.5,
      "total_measurements": 12456,
      "previous_avg_value": 1920.45,
      "previous_p75": 2180.23,
      "previous_p90": 2400.56,
      "previous_p95": 2480.78,
      "previous_p99": 2499.90,
      "previous_measurement_count": 7234,
      "previous_total_measurements": 11890,
      "previous_percentage": 60.8,
      "avg_value_growth_percentage": -3.66,
      "measurement_count_growth_percentage": 17.94,
      "score": 100,
      "units": "ms",
      "thresholds": "Excellent: ≤2500ms, Good: ≤4000ms, Poor: >4000ms",
      "description": "Largest Contentful Paint - measures loading performance",
      "domain": "example.com"
    },
    {
      "metric_name": "LCP",
      "performance_category": "good",
      "avg_value": 3234.56,
      "p75": 3456.78,
      "p90": 3678.90,
      "p95": 3890.12,
      "p99": 3999.34,
      "measurement_count": 2876,
      "percentage": 23.1,
      "total_measurements": 12456,
      "previous_avg_value": 3345.67,
      "previous_p75": 3567.89,
      "previous_p90": 3789.01,
      "previous_p95": 3901.23,
      "previous_p99": 3998.45,
      "previous_measurement_count": 3234,
      "previous_total_measurements": 11890,
      "previous_percentage": 27.2,
      "avg_value_growth_percentage": -3.32,
      "measurement_count_growth_percentage": -11.07,
      "score": 75,
      "units": "ms",
      "thresholds": "Excellent: ≤2500ms, Good: ≤4000ms, Poor: >4000ms",
      "description": "Largest Contentful Paint - measures loading performance",
      "domain": "example.com"
    },
    {
      "metric_name": "LCP",
      "performance_category": "poor",
      "avg_value": 5234.78,
      "p75": 5678.90,
      "p90": 6789.01,
      "p95": 7890.12,
      "p99": 9876.54,
      "measurement_count": 1048,
      "percentage": 8.4,
      "total_measurements": 12456,
      "previous_avg_value": 5567.89,
      "previous_p75": 6012.34,
      "previous_p90": 7123.45,
      "previous_p95": 8234.56,
      "previous_p99": 10234.78,
      "previous_measurement_count": 1422,
      "previous_total_measurements": 11890,
      "previous_percentage": 12.0,
      "avg_value_growth_percentage": -5.98,
      "measurement_count_growth_percentage": -26.30,
      "score": 25,
      "units": "ms",
      "thresholds": "Excellent: ≤2500ms, Good: ≤4000ms, Poor: >4000ms",
      "description": "Largest Contentful Paint - measures loading performance",
      "domain": "example.com"
    }
  ]
}

​
Use Cases

  • Performance Distribution Analysis: Understand what percentage of your users experience excellent, good, or poor performance
  • Trend Analysis: Track how distribution changes over time with period-over-period comparison
  • Goal Setting: Monitor progress toward improving the percentage of excellent experiences
  • Performance Regression Detection: Identify when the distribution shifts toward poor performance
  • User Experience Insights: Understand the full spectrum of performance your users experience

Build docs developers (and LLMs) love

Get started for freeTalk to us