---
title: "Aggregates page views"
method: GET
path: "/v1/query/web-analytics/visits/aggregate"
tags: ["web-analytics"]
---

# Aggregates page views

`GET /v1/query/web-analytics/visits/aggregate`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v1/query/web-analytics/visits/aggregate`
- Auth: HTTP bearer

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.

## Query parameters

- `projectId` string, required: The project identifier or the project name
- `by` union[], required: 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'.
  - union
    - 'hour' | 'day' | 'week' | 'month' | 'year' | 'country' | 'deviceType' | 'environment' | 'requestPath' | 'referrerHostname' | 'osName' | 'browserName' | 'route' | 'utmSource' | 'utmMedium' | 'utmCampaign' | 'utmContent' | 'utmTerm' | 'flags'
    - string
- `since` union, required: 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.
  - number
  - string
- `until` union, required: Timestamp in milliseconds, or a valid Date string. Selects data until (including) this date. Will be adjusted according to the desired time granularity.
  - number
  - string
- `limit` integer: Number of distinct results, default to 10. Other results are grouped into "Others" group.
- `filter` string: 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/<name>, for example flags/beta_banner eq 'true'. Wrap keys containing characters other than letters, digits, and underscores in single quotes, for example flags/'my-flag' eq 'true'. Supported operations include eq, ne, in, and logical operators and, or, not with parentheses. Functions such as startswith are supported by the OData parser.
- `teamId` string
- `slug` string

## Response `200`

- object
  - `data` union, required
    - object[]
      - `browserName` string
      - `country` string
      - `deviceType` string
      - `environment` string
      - `flags` string
      - `groupId` string
      - `osName` string
      - `projectId` string
      - `projectName` string
      - `referrerHostname` string
      - `requestHostname` string
      - `requestPath` string
      - `route` string
      - `userId` string
      - `utmCampaign` string
      - `utmContent` string
      - `utmMedium` string
      - `utmSource` string
      - `utmTerm` string
      - `visitorId` string
      - `timestamp` string, date-time, required
    - object[]
      - `browserName` string, required
      - `country` string, required
      - `deviceType` string, required
      - `environment` string, required
      - `flags` string, required
      - `groupId` string, required
      - `osName` string, required
      - `projectId` string, required
      - `projectName` string, required
      - `referrerHostname` string, required
      - `requestHostname` string, required
      - `requestPath` string, required
      - `route` string, required
      - `userId` string, required
      - `utmCampaign` string, required
      - `utmContent` string, required
      - `utmMedium` string, required
      - `utmSource` string, required
      - `utmTerm` string, required
      - `visitorId` string, required
  - `query` object, required
    - `filter` string
    - `groupBy` union[]
      - union
        - string
        - 'browserName' | 'country' | 'deviceType' | 'environment' | 'flags' | 'osName' | 'referrerHostname' | 'requestPath' | 'route' | 'utmCampaign' | 'utmContent' | 'utmMedium' | 'utmSource' | 'utmTerm'
    - `limit` number, required
    - `since` string, required
    - `until` string, required
  - `version` number, required

## Other responses

- `400`: One of the provided values in the request query is invalid.
- `401`: The request is not authorized.
- `402`
- `403`: You do not have permission to access this resource.
- `404`
- `410`
- `503`

## Changes

- **2026-10-23** `5a120284f519`: 1 breaking, 1 info
  - added `subschema #1, subschema #2` to the `data` response property `oneOf` list for the response status `200`
  - removed `subschema #1, subschema #2` from the `data` response property `oneOf` list for the response status `200`
- **2026-10-03** `2c463a1d98b1`: 1 warning
  - for the `query` request parameter `filter`, the maxLength was set to `2048`
- **2026-09-26** `9688d14fb03a`: 1 breaking, 1 info
  - added `subschema #1, subschema #2` to the `data` response property `oneOf` list for the response status `200`
  - removed `subschema #1, subschema #2` from the `data` response property `oneOf` list for the response status `200`
- **2026-09-25** `7881412aa042`: 1 breaking, 1 info
  - added `subschema #1, subschema #2` to the `data` response property `oneOf` list for the response status `200`
  - removed `subschema #1, subschema #2` from the `data` response property `oneOf` list for the response status `200`
- **2026-09-22** `0f7ea3d3b39b`: 1 breaking, 1 info
  - added `subschema #1, subschema #2` to the `data` response property `oneOf` list for the response status `200`
  - removed `subschema #1, subschema #2` from the `data` response property `oneOf` list for the response status `200`

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v1/query/web-analytics/visits/aggregate/get.md)

---

[API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)