Overview
The top_browsers endpoint returns the most used browsers ranked by number of visits. It supports pagination and optional comparison with the previous period.
Endpoint
GET https://api.tinybird.co/v0/pipes/top_browsers.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 browser data from analytics_sessions_mv:
SELECT
browser,
uniq(session_id) as current_visits,
countMerge(hits) as current_hits
FROM analytics_sessions_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 browser
Response
The browser name (e.g., “Chrome”, “Firefox”, “Safari”)
Number of unique visits from this browser
Total number of pageviews from this browser
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 browsers (default)
const result = await tinybird.query.topBrowsers();
result.data.forEach(browser => {
console.log(`${browser.browser}: ${browser.visits} visits, ${browser.hits} pageviews`);
});
// Get top browsers for a specific date range
const rangeResult = await tinybird.query.topBrowsers({
date_from: '2024-01-01',
date_to: '2024-01-31',
domain: 'example.com',
limit: 10
});
// Get top browsers with previous period comparison
const comparisonResult = await tinybird.query.topBrowsers({
date_from: '2024-01-01',
date_to: '2024-01-07',
include_previous_period: 'true',
limit: 20
});
comparisonResult.data.forEach(browser => {
console.log(`${browser.browser}: ${browser.visits} visits (${browser.visits_growth_percentage}% growth)`);
});
// Paginate through results
const page1 = await tinybird.query.topBrowsers({
skip: 0,
limit: 10
});
const page2 = await tinybird.query.topBrowsers({
skip: 10,
limit: 10
});
Example Response
Without Previous Period
{
"data": [
{
"browser": "Chrome",
"visits": 12456,
"hits": 28934
},
{
"browser": "Safari",
"visits": 5234,
"hits": 11234
},
{
"browser": "Firefox",
"visits": 3421,
"hits": 7865
},
{
"browser": "Edge",
"visits": 1876,
"hits": 4321
}
]
}
With Previous Period
{
"data": [
{
"browser": "Chrome",
"visits": 12456,
"hits": 28934,
"previous_visits": 11234,
"previous_hits": 26543,
"visits_growth_percentage": 10.88,
"hits_growth_percentage": 9.01
},
{
"browser": "Safari",
"visits": 5234,
"hits": 11234,
"previous_visits": 4876,
"previous_hits": 10543,
"visits_growth_percentage": 7.34,
"hits_growth_percentage": 6.55
}
]
}
Notes
- Browser names are detected from User-Agent strings
- Results are ordered by visits in descending order
- Use pagination parameters for large result sets
