Overview
The top_pages endpoint returns the most visited pages ranked by number of visits. It supports pagination and optional comparison with the previous period.
Endpoint
GET https://api.tinybird.co/v0/pipes/top_pages.json
Parameters
Start date (YYYY-MM-DD format). Defaults to 7 days ago.
End date (YYYY-MM-DD format). Defaults to today.
Set to “true” to include previous period comparison and growth percentages
Skip for pagination (offset)
Limit for pagination (max results)
SQL Query
The endpoint aggregates page data from analytics_pages_mv:
SELECT
pathname,
uniqMerge(visits) as current_visits,
countMerge(hits) as current_hits
FROM analytics_pages_mv
WHERE date >= (SELECT current_start FROM date_calculations)
AND date <= (SELECT current_end FROM date_calculations)
{% if defined(tenant_id) %}
AND tenant_id = {{ String(tenant_id, description="Filter by tenant ID") }}
{% end %}
{% if defined(domain) %}
AND domain = {{ String(domain, description="Filter by domain") }}
{% end %}
GROUP BY pathname
Response
The page pathname (URL path)
Number of unique visits to this page
Total number of pageviews for this page
Previous period visits (only when include_previous_period=true)
Previous period pageviews (only when include_previous_period=true)
Percentage change in visits (only when include_previous_period=true)
Percentage change in pageviews (only when include_previous_period=true)
TypeScript Usage
import { createAnalyticsClient } from '@tinybirdco/analytics-client';
const tinybird = createAnalyticsClient();
// Get top 50 pages (default)
const result = await tinybird.query.topPages();
result.data.forEach(page => {
console.log(`${page.pathname}: ${page.visits} visits, ${page.hits} pageviews`);
});
// Get top pages for a specific date range
const rangeResult = await tinybird.query.topPages({
date_from: '2024-01-01',
date_to: '2024-01-31',
domain: 'example.com',
limit: 10
});
// Get top pages with previous period comparison
const comparisonResult = await tinybird.query.topPages({
date_from: '2024-01-01',
date_to: '2024-01-07',
include_previous_period: 'true',
limit: 20
});
comparisonResult.data.forEach(page => {
console.log(`${page.pathname}: ${page.visits} visits (${page.visits_growth_percentage}% growth)`);
});
// Paginate through results
const page1 = await tinybird.query.topPages({
skip: 0,
limit: 10
});
const page2 = await tinybird.query.topPages({
skip: 10,
limit: 10
});
Example Response
Without Previous Period
{
"data": [
{
"pathname": "/",
"visits": 8234,
"hits": 12456
},
{
"pathname": "/docs",
"visits": 3421,
"hits": 8932
},
{
"pathname": "/blog",
"visits": 2145,
"hits": 3876
}
]
}
With Previous Period
{
"data": [
{
"pathname": "/",
"visits": 8234,
"hits": 12456,
"previous_visits": 7521,
"previous_hits": 11234,
"visits_growth_percentage": 9.48,
"hits_growth_percentage": 10.88
},
{
"pathname": "/docs",
"visits": 3421,
"hits": 8932,
"previous_visits": 2987,
"previous_hits": 7654,
"visits_growth_percentage": 14.53,
"hits_growth_percentage": 16.70
}
]
}
