Skip to main content
GET
/
web_vitals_timeseries
Web Vitals Timeseries
curl --request GET \
  --url https://api.example.com/web_vitals_timeseries
{
  "hour": {},
  "metric_name": "<string>",
  "p75": 123,
  "p90": 123,
  "p95": 123,
  "p99": 123,
  "measurements": 123,
  "domain": "<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 hourly aggregated web vitals data with percentile values, allowing you to visualize performance trends over time and identify patterns or anomalies.

​
Endpoint

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

​
Parameters

​
date_from
date
Start date for the time series (YYYY-MM-DD format). If not provided, returns recent data.
​
date_to
date
End date for the time series (YYYY-MM-DD format). If not provided, uses current date.
​
tenant_id
string
Filter results by tenant ID for multi-tenant applications.
​
domain
string
Filter results by domain name (e.g., “example.com”).

​
Web Vitals Metrics Tracked

This endpoint provides time series data for all five Core Web Vitals metrics:

​
LCP (Largest Contentful Paint)

Measures loading performance over time.
  • Excellent: ≤2500ms
  • Good: ≤4000ms
  • Poor: >4000ms

​
TTFB (Time to First Byte)

Measures server response time trends.
  • Excellent: ≤500ms
  • Good: ≤1000ms
  • Poor: >1000ms

​
FCP (First Contentful Paint)

Measures perceived load speed over time.
  • Excellent: ≤1800ms
  • Good: ≤3000ms
  • Poor: >3000ms

​
INP (Interaction to Next Paint)

Measures responsiveness trends.
  • Excellent: ≤200ms
  • Good: ≤500ms
  • Poor: >500ms

​
CLS (Cumulative Layout Shift)

Measures visual stability patterns.
  • Excellent: ≤0.1
  • Good: ≤0.25
  • Poor: >0.25

​
Response Fields

​
hour
datetime
The hour timestamp for this data point (rounded to the start of the hour).
​
metric_name
string
The name of the web vitals metric (LCP, TTFB, FCP, INP, or CLS).
​
p75
float
75th percentile value for this hour. 75% of users experienced this value or better.
​
p90
float
90th percentile value for this hour. 90% of users experienced this value or better.
​
p95
float
95th percentile value for this hour. 95% of users experienced this value or better.
​
p99
float
99th percentile value for this hour. 99% of users experienced this value or better.
​
measurements
integer
Total number of measurements collected during this hour.
​
domain
string
The domain this data was collected from.

​
Example Request

​
Last 7 Days

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.tinybird.co/v0/pipes/web_vitals_timeseries.json?date_from=2024-01-01&date_to=2024-01-07&domain=example.com"

​
Specific Date Range

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.tinybird.co/v0/pipes/web_vitals_timeseries.json?date_from=2024-01-15&date_to=2024-01-22"

​
Example Response

{
  "data": [
    {
      "hour": "2024-01-01T00:00:00Z",
      "metric_name": "LCP",
      "p75": 2345.67,
      "p90": 3456.78,
      "p95": 4012.34,
      "p99": 5234.56,
      "measurements": 1523,
      "domain": "example.com"
    },
    {
      "hour": "2024-01-01T01:00:00Z",
      "metric_name": "LCP",
      "p75": 2289.45,
      "p90": 3312.56,
      "p95": 3945.67,
      "p99": 5012.34,
      "measurements": 1456,
      "domain": "example.com"
    },
    {
      "hour": "2024-01-01T00:00:00Z",
      "metric_name": "TTFB",
      "p75": 412.34,
      "p90": 567.89,
      "p95": 678.90,
      "p99": 890.12,
      "measurements": 1523,
      "domain": "example.com"
    },
    {
      "hour": "2024-01-01T01:00:00Z",
      "metric_name": "TTFB",
      "p75": 398.67,
      "p90": 545.23,
      "p95": 654.32,
      "p99": 876.54,
      "measurements": 1456,
      "domain": "example.com"
    },
    {
      "hour": "2024-01-01T00:00:00Z",
      "metric_name": "FCP",
      "p75": 1845.67,
      "p90": 2456.78,
      "p95": 2812.34,
      "p99": 3234.56,
      "measurements": 1523,
      "domain": "example.com"
    },
    {
      "hour": "2024-01-01T00:00:00Z",
      "metric_name": "INP",
      "p75": 178.90,
      "p90": 234.56,
      "p95": 312.34,
      "p99": 456.78,
      "measurements": 1245,
      "domain": "example.com"
    },
    {
      "hour": "2024-01-01T00:00:00Z",
      "metric_name": "CLS",
      "p75": 0.09,
      "p90": 0.15,
      "p95": 0.22,
      "p99": 0.34,
      "measurements": 1523,
      "domain": "example.com"
    }
  ]
}

​
Percentile Interpretation

Percentile values help you understand the distribution of your performance:
  • p75 (75th percentile): The “typical” user experience. Google recommends optimizing to meet Web Vitals thresholds at p75.
  • p90 (90th percentile): Captures most users but includes some outliers.
  • p95 (95th percentile): Helps identify performance issues affecting a smaller subset of users.
  • p99 (99th percentile): The worst-case scenarios, useful for identifying extreme performance problems.

​
Use Cases

  • Performance Visualization: Create line charts showing how metrics trend over time
  • Anomaly Detection: Identify unusual spikes or drops in performance
  • Deployment Impact Analysis: Compare performance before and after deployments
  • Time-of-Day Patterns: Discover if performance varies by time of day or day of week
  • Capacity Planning: Identify peak usage times and their performance impact
  • SLA Monitoring: Track whether performance meets service level agreements over time
  • Regression Detection: Quickly spot when performance degrades
  • Seasonal Analysis: Understand how performance changes during high-traffic periods

​
Visualization Examples

​
Time Series Line Chart

Plot p75, p90, or p95 values over time to see trends. Each metric can be a separate line or separate chart.

​
Heatmap

Create a heatmap showing performance intensity by hour and day of week to identify patterns.

​
Threshold Comparison

Overlay the “Good” and “Excellent” thresholds on your time series to visualize how often you meet Web Vitals standards.

​
Notes

  • Hours with fewer than 5 measurements are excluded to ensure data quality
  • Data is aggregated at the start of each hour (e.g., 14:00:00 includes data from 14:00:00 to 14:59:59)
  • For real-time monitoring, query recent hours with shorter date ranges
  • Consider the p75 metric as your primary performance indicator, as it aligns with Google’s Core Web Vitals assessment
  • Large date ranges may return substantial data - consider using data visualization tools that can handle time series efficiently

Build docs developers (and LLMs) love

Get started for freeTalk to us