aggregates page views.md
title: aggregates-page-views product: vercel url: /docs/rest-api/web-analytics/aggregates-page-views canonical_url: "https://vercel.com/docs/rest-api/web-analytics/aggregates-page-views" last_updated: 2026-09-26 type: reference prerequisites: [] summary: Learn about aggregates-page-views on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin
Aggregates page views
GET /v1/query/web-analytics/visits/aggregate
Counts pageviews on a project, within the requested date range. Results are either aggregated or broken down over time. Results can additionally be broken down by one dimension, and filtered by multiple dimensions.
Authentication
bearerToken: HTTP bearer
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
projectId |
string | Yes | The project identifier or the project name |
by |
array | Yes | Up to two dimensions used to break down results. At most one time granularity is allowed: hour, day, week, month, year. Other dimensions: country, deviceType, environment, requestPath, referrerHostname, osName, browserName, route, utmSource, utmMedium, utmCampaign, utmContent, utmTerm. JSON dimensions: flags. Used bare, it breaks down results by key, for example flags returns one group per flag name. With a key, it breaks down results by that key's value, for example flags/beta_banner. Wrap keys containing characters other than letters, digits, and underscores in single quotes, for example flags/'my-flag'. |
since |
object | Yes | Timestamp in milliseconds, or a valid Date string. Selects data from (including) this date and time. Will be adjusted according to the desired time granularity. |
until |
object | Yes | Timestamp in milliseconds, or a valid Date string. Selects data until (including) this date. Will be adjusted according to the desired time granularity. |
limit |
integer. min: 1; max: 100; default: 10 | No | Number of distinct results, default to 10. Other results are grouped into "Others" group. |
filter |
string | No | OData-compliant filter. Encode the value when sending it in a URL. Allows filtering on one or multiple dimensions. By default, filters for production environment only. Supported dimensions: country, deviceType, environment, requestPath, referrerHostname, osName, browserName, route, utmSource, utmMedium, utmCampaign, utmContent, utmTerm. JSON dimensions filtered by key: flags/ |
teamId |
string | No | The Team identifier to perform the request on behalf of. |
slug |
string | No | The Team slug to perform the request on behalf of. |
Example request
TypeScript
const response = await fetch('https://api.vercel.com/v1/query/web-analytics/visits/aggregate?projectId=string&by=[]&since=value&until=value&limit=123&filter=string&teamId=string&slug=string', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json',
},
});
const data = await response.json();
console.log(data);
Next.js
'use server';
export async function callEndpoint() {
const response = await fetch('https://api.vercel.com/v1/query/web-analytics/visits/aggregate?projectId=string&by=[]&since=value&until=value&limit=123&filter=string&teamId=string&slug=string', {
method: 'GET',
headers: {
'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
next: { revalidate: 3600 }
});
if (!response.ok) {
throw new Error('Request failed');
}
return response.json();
}
cURL
curl -X GET 'https://api.vercel.com/v1/query/web-analytics/visits/aggregate?projectId=string&by=[]&since=value&until=value&limit=123&filter=string&teamId=string&slug=string' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json'
Example response
{
"data": [
{
"browserName": "Example Name",
"country": "string",
"deviceType": "string",
"environment": "string",
"flags": "string",
"osName": "Example Name",
"projectId": "example_id",
"projectName": "Example Name",
"referrerHostname": "Example Name",
"requestHostname": "Example Name",
"requestPath": "string",
"route": "string",
"utmCampaign": "string",
"utmContent": "string",
"utmMedium": "string",
"utmSource": "string",
"utmTerm": "string",
"visitorId": "example_id",
"timestamp": "2024-01-01T00:00:00Z"
}
],
"query": {
"filter": "string",
"groupBy": [],
"limit": "123",
"since": "string",
"until": "string"
},
"version": "123"
}
Responses
200: No description
Content-Type: application/json
{
"type": "object",
"required": [
"data",
"query",
"version"
],
"properties": {
"data": {
"oneOf": [
{
"type": "array",
"items": {
"type": "object",
"required": [
"timestamp"
]
}
},
{
"type": "array",
"items": {
"type": "object",
"required": [
"browserName",
"country",
"deviceType",
"environment",
"flags",
"osName",
"projectId",
"projectName",
"referrerHostname",
"requestHostname",
"requestPath",
"route",
"utmCampaign",
"utmContent",
"utmMedium",
"utmSource",
"utmTerm",
"visitorId"
]
}
}
]
},
"query": {
"type": "object",
"required": [
"limit",
"since",
"until"
],
"properties": {
"filter": {
"type": "string"
},
"groupBy": {
"type": "array",
"items": {}
},
"limit": {
"type": "number"
},
"since": {
"type": "string"
},
"until": {
"type": "string"
}
}
},
"version": {
"type": "number"
}
}
}