--- title: Web Analytics product: vercel url: /docs/agent-resources/vercel-mcp/tools/web-analytics canonical_url: "https://vercel.com/docs/agent-resources/vercel-mcp/tools/web-analytics" last_updated: 2018-10-20 type: reference prerequisites: - /docs/agent-resources/vercel-mcp/tools - /docs/agent-resources/vercel-mcp related: - /docs/analytics summary: Vercel MCP tools for web analytics. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Web Analytics Explore traffic and custom events for projects with Web Analytics enabled. You can count page views and events or aggregate them to understand how visitors use your application. ## Related pages > **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below. - [Counts custom events](https://vercel.com/docs/rest-api/web-analytics/counts-custom-events) — GET /v1/query/web-analytics/events/count — Counts the number of custom events on a project \\(production only\\), since We - [Aggregates custom events](https://vercel.com/docs/rest-api/web-analytics/aggregates-custom-events) — GET /v1/query/web-analytics/events/aggregate — Counts custom events on a project, within the requested date range. Resul - [Query Web Analytics with the API](https://vercel.com/docs/analytics/web-analytics-api) — Learn how Web Analytics concepts map to API queries for custom reports, dashboards, and insights. - [Aggregates page views](https://vercel.com/docs/rest-api/web-analytics/aggregates-page-views) — GET /v1/query/web-analytics/visits/aggregate — Counts pageviews on a project, within the requested date range. Results a - [Counts page views](https://vercel.com/docs/rest-api/web-analytics/counts-page-views) — GET /v1/query/web-analytics/visits/count — Counts the number of page views on a project \\(production only\\), since Web A Full cross-link map for this page: [/docs/agent-resources/vercel-mcp/tools/web-analytics.graph.md](/docs/agent-resources/vercel-mcp/tools/web-analytics.graph.md) ## `aggregate_events` Aggregates custom events. Enable [Web Analytics](/docs/analytics) for your project before querying its data. ## Parameters | Parameter | 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, eventName. JSON dimensions: flags, eventData. Used bare, they break down results by key, for example flags returns one group per flag name. With a key, they break down results by that key's value, for example eventData/plan. Wrap keys containing characters other than letters, digits, and underscores in single quotes, for example flags/'my-flag'. | | `since` | number \| string | 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` | number \| string | 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 | No | Number of distinct results, Other results are grouped into "Others" group. Minimum: 1. Maximum: 100. Default: `10`. | | `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, eventName. JSON dimensions filtered by key: flags/\, eventData/\, for example eventData/plan eq 'pro'. 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 | No | Team ID to use for this operation. | | `slug` | string | No | Team slug to use for this operation. Use instead of teamId. | ## `aggregate_pageviews` Aggregates page views. Enable [Web Analytics](/docs/analytics) for your project before querying its data. ## Parameters | Parameter | 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` | number \| string | 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` | number \| string | 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 | No | Number of distinct results, Other results are grouped into "Others" group. Minimum: 1. Maximum: 100. Default: `10`. | | `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/\, 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 | No | Team ID to use for this operation. | | `slug` | string | No | Team slug to use for this operation. Use instead of teamId. | ## `count_events` Counts custom events. Enable [Web Analytics](/docs/analytics) for your project before querying its data. ## Parameters | Parameter | Type | Required | Description | | ----------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `projectId` | string | Yes | The project identifier or the project name | | `since` | number \| string | No | 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` | number \| string | No | Timestamp in milliseconds, or a valid Date string. Selects data until (including) this date. Will be adjusted according to the desired time granularity. | | `filter` | string | No | OData-compliant filter. Encode the value when sending it in a URL. Allows filtering on one or multiple dimensions. Supported dimensions: country, deviceType, environment, requestPath, referrerHostname, osName, browserName, route, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, eventName. JSON dimensions filtered by key: flags/\, eventData/\, for example eventData/plan eq 'pro'. 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 | No | Team ID to use for this operation. | | `slug` | string | No | Team slug to use for this operation. Use instead of teamId. | ## `count_pageviews` Counts page views. Enable [Web Analytics](/docs/analytics) for your project before querying its data. ## Parameters | Parameter | Type | Required | Description | | ----------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `projectId` | string | Yes | The project identifier or the project name | | `since` | number \| string | No | 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` | number \| string | No | Timestamp in milliseconds, or a valid Date string. Selects data until (including) this date. Will be adjusted according to the desired time granularity. | | `filter` | string | No | OData-compliant filter. Encode the value when sending it in a URL. Allows filtering on one or multiple dimensions. Supported dimensions: country, deviceType, environment, requestPath, referrerHostname, osName, browserName, route, utmSource, utmMedium, utmCampaign, utmContent, utmTerm. JSON dimensions filtered by key: flags/\, 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 | No | Team ID to use for this operation. | | `slug` | string | No | Team slug to use for this operation. Use instead of teamId. | ## `get_web_analytics` Query Web Analytics for a Vercel project. Count mode returns total visitors and pageviews (or custom event count). Aggregate mode groups results over time or by dimensions such as route, requestPath, country, referrerHostname, deviceType, browserName, eventName, `flags/`, or `eventData/`. Web Analytics must be enabled for the project. ## Parameters | Parameter | Type | Required | Default | Description | | ----------- | ---------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `teamId` | string | No | - | The team ID or slug. Use the team that owns the resource. | | `projectId` | string | Yes | - | The project ID or slug. Find the project ID in `.vercel/project.json` or use `list_projects`. | | `dataset` | string | No | - | Data to query: visits for automatically tracked pageviews, or events for custom events sent with track(). Defaults to visits. Allowed values: `"visits"`, `"events"`. | | `mode` | string | No | - | Count returns one total. Aggregate returns rows grouped by one or two by dimensions and requires since, until, and by. Defaults to count. Allowed values: `"count"`, `"aggregate"`. | | `since` | string \| number | No | - | Start or end of the date range as a date string, ISO 8601 timestamp, or Unix timestamp in milliseconds. Since and until must be provided together. | | `until` | string \| number | No | - | Start or end of the date range as a date string, ISO 8601 timestamp, or Unix timestamp in milliseconds. Since and until must be provided together. | | `by` | Array\ | No | - | One or two dimensions for aggregate mode. Time dimensions: hour, day, week, month, year. Other common dimensions: country, deviceType, environment, requestPath, referrerHostname, osName, browserName, route, UTM fields, eventName, flags/\, and eventData/\. | | `filter` | string | No | - | OData filter expression, for example requestPath eq '/pricing' and country eq 'US', eventName eq 'signup', or eventData/plan eq 'pro'. | | `limit` | integer | No | - | Maximum distinct results in aggregate mode. Remaining values are grouped into Others. Defaults to 10. Minimum: 1. Maximum: 100. | --- [View full sitemap](/docs/sitemap)