Overview
The kpis endpoint returns time-series KPI data including visits, pageviews, bounce rate, and average session duration. It supports optional comparison with the previous period to calculate growth percentages.
Endpoint
GET https://api.tinybird.co/v0/pipes/kpis.json
Parameters
Starting day (YYYY-MM-DD format). Defaults to 7 days ago.
Finishing day (YYYY-MM-DD format). Defaults to today.
Set to “true” to include previous period comparison and growth percentages
SQL Query
The endpoint uses a multi-node pipeline:
Date Calculations
WITH
{% if defined(date_from) %}
toStartOfDay(toDate({{ String(date_from, description="Starting day") }})) as current_start,
{% else %} toStartOfDay(timestampAdd(today(), interval -7 day)) as current_start,
{% end %}
{% if defined(date_to) %}
toStartOfDay(toDate({{ String(date_to, description="Finishing day") }})) as current_end
{% else %} toStartOfDay(today()) as current_end
{% end %}
SELECT
current_start,
current_end,
dateDiff('day', current_start, current_end) + 1 as period_days,
timestampAdd(current_start, interval -dateDiff('day', current_start, current_end) - 1 day) as previous_start,
timestampAdd(current_end, interval -dateDiff('day', current_start, current_end) - 1 day) as previous_end
Session Metrics
The endpoint aggregates session data from analytics_sessions_mv (or analytics_hits for same-day queries) to calculate:
- Unique visits per session
- Pageviews per session
- Bounce rate (single-page sessions)
- Average session duration
Response
The date for this data point
Number of unique visits (sessions)
Total number of pageviews
Bounce rate (0-1, where 1 = 100%)
Average session duration in seconds
Previous period visits (only when include_previous_period=true)
Previous period pageviews (only when include_previous_period=true)
Previous period bounce rate (only when include_previous_period=true)
Previous period average session duration (only when include_previous_period=true)
Percentage change in visits (only when include_previous_period=true)
pageviews_growth_percentage
Percentage change in pageviews (only when include_previous_period=true)
bounce_rate_growth_percentage
Percentage change in bounce rate (only when include_previous_period=true)
avg_session_sec_growth_percentage
Percentage change in average session duration (only when include_previous_period=true)
TypeScript Usage
import { createAnalyticsClient } from '@tinybirdco/analytics-client';
const tinybird = createAnalyticsClient();
// Get KPIs for the last 7 days (default)
const result = await tinybird.query.kpis();
result.data.forEach(day => {
console.log(`${day.date}: ${day.visits} visits, ${day.pageviews} pageviews`);
});
// Get KPIs for a specific date range
const rangeResult = await tinybird.query.kpis({
date_from: '2024-01-01',
date_to: '2024-01-31',
domain: 'example.com'
});
// Get KPIs with previous period comparison
const comparisonResult = await tinybird.query.kpis({
date_from: '2024-01-01',
date_to: '2024-01-07',
include_previous_period: 'true'
});
comparisonResult.data.forEach(day => {
console.log(`${day.date}: ${day.visits} visits (${day.visits_growth_percentage}% growth)`);
});
Example Response
Without Previous Period
{
"data": [
{
"date": "2024-01-01",
"visits": 1523,
"pageviews": 4829,
"bounce_rate": 0.42,
"avg_session_sec": 145.6
},
{
"date": "2024-01-02",
"visits": 1678,
"pageviews": 5234,
"bounce_rate": 0.38,
"avg_session_sec": 152.3
}
]
}
With Previous Period
{
"data": [
{
"date": "2024-01-01",
"visits": 1523,
"pageviews": 4829,
"bounce_rate": 0.42,
"avg_session_sec": 145.6,
"previous_visits": 1401,
"previous_pageviews": 4321,
"previous_bounce_rate": 0.45,
"previous_avg_session_sec": 138.2,
"visits_growth_percentage": 8.71,
"pageviews_growth_percentage": 11.75,
"bounce_rate_growth_percentage": -6.67,
"avg_session_sec_growth_percentage": 5.35
}
]
}
