--- title: aggregates-page-views product: vercel url: /docs/rest-api/sdk/web-analytics/aggregates-page-views canonical_url: "https://vercel.com/docs/rest-api/sdk/web-analytics/aggregates-page-views" last_updated: 2026-08-29 type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about aggregates-page-views on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Aggregates page views ```http 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/, 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 | 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 import { Vercel } from "@vercel/sdk"; const vercel = new Vercel({ bearerToken: "", }); async function run() { const result = await vercel.webAnalytics.aggregatePageviews({ projectId: "prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA", by: [ "day", "country", ], since: "2024-09-01T00:00:00.000Z", until: "2024-09-08T00:00:00.000Z", limit: 3, filter: "requestPath eq '/docs'", teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l", slug: "my-team-url-slug", }); console.log(result); } run(); ``` ## Example response ```json { "version": "123", "query": { "since": "string", "until": "string", "groupBy": [], "filter": "string", "limit": "123" }, "data": [ { "projectId": "example_id", "country": "string", "deviceType": "string", "environment": "string", "requestPath": "string", "referrerHostname": "Example Name", "osName": "Example Name", "browserName": "Example Name", "route": "string", "utmSource": "string", "utmMedium": "string", "utmCampaign": "string", "utmContent": "string", "utmTerm": "string", "flags": "string", "errorMessage": "string", "entryRevalidateSeconds": "example_id", "projectName": "Example Name", "deploymentId": "example_id", "pathType": "string", "pathTypeVariant": "string", "requestHostname": "Example Name", "requestResolvedIp": "string", "requestMethod": "string", "requestExtension": "string", "requestId": "example_id", "requestApi": "string", "referrerUrl": "https://example.com", "serverActionName": "Example Name", "httpStatus": "string", "errorCode": "string", "source": "string", "edgeType": "string", "reason": "Customer requested refund", "edgeNetworkRegion": "string", "functionRegion": "string", "imageTransformationRegion": "string", "dataCacheRegion": "string", "cause": "string", "runtime": "string", "provider": "example_id", "isrCacheRegion": "string", "isrAction": "string", "cacheResult": "string", "cacheOperation": "string", "cacheHostname": "Example Name", "cachePath": "string", "cacheHitState": "string", "cacheHitLevel": "string", "cacheApi": "string", "cacheReason": "Customer requested refund", "pprState": "string", "clientIp": "string", "clientIpCountry": "string", "clientUserAgent": "string", "httpAccept": "string", "clientJa4Digest": "string", "asnId": "example_id", "asnName": "Example Name", "botName": "Example Name", "botCategory": "string", "botCategoryLegacy": "string", "botVerified": "string", "botCheckResult": "string", "deepAnalysisCheck": "string", "wafAction": "string", "wafRuleId": "example_id", "ruleCategory": "string", "skewProtection": "string", "functionStartType": "string", "functionDispatcher": "string", "isAdditionalRequest": "string", "originHostname": "Example Name", "originPath": "string", "originRoute": "string", "fetchType": "string", "fetchIndex": "string", "imageSource": "string", "sourceImage": "string", "sourceImagePathname": "Example Name", "sourceImageHostname": "Example Name", "sourceImageHash": "string", "optimizedQuality": "string", "optimizedWidthPixels": "example_id", "optimizedFormatMimeType": "string", "vdcOperationOrigin": "string", "entryName": "Example Name", "entryId": "example_id", "entryItemId": "example_id", "tagName": "Example Name", "cacheTags": "string", "storeId": "example_id", "storeName": "Example Name", "blobOperationType": "string", "blobOperationLevel": "string", "visitorId": "example_id", "eventName": "Example Name", "attributionTarget": "string", "attributionEventName": "Example Name", "metricName": "Example Name", "attributes": "string", "flagKey": "string", "flagVariant": "string", "flagEvaluationReason": "Customer requested refund", "flagClientName": "Example Name", "sdkKeyId": "example_id", "sdkKeyEnvironment": "string", "reportingProjectId": "example_id", "reportingProjectName": "Example Name", "eventData": "string", "middlewareAction": "example_id", "middlewareActionTarget": "example_id", "aiModel": "string", "aiGatewayModelId": "example_id", "aiProvider": "example_id", "aiModelType": "string", "servedSpeed": "string", "virtualModelSlug": "string", "virtualModelKind": "string", "inferenceEndpointSlug": "string", "inferenceScope": "string", "inferenceGeoRegion": "string", "inferenceProviderRegion": "example_id", "requestedInferenceRegion": "string", "costCurrency": "string", "marketCostCurrency": "string", "cachedInputTokensCurrency": "string", "cacheCreationInputTokensCurrency": "string", "cacheCreation1hInputTokensCurrency": "string", "surchargeCostCurrency": "string", "gatewayCostCurrency": "string", "keyId": "example_id", "keyName": "Example Name", "authMethod": "string", "appName": "Example Name", "codingAgent": "string", "isByok": "string", "spendAttribution": "string", "isPrivateModel": "string", "isRequestZdr": "string", "hipaaRequested": "string", "quotaRequested": "string", "quotaEntityId": "example_id", "quotaEntityType": "string", "videoResolution": "example_id", "videoAspectRatio": "example_id", "piiRedactionApplied": "string", "moderationApplied": "string", "queueName": "Example Name", "consumerGroup": "string", "messageId": "example_id", "eventType": "string", "notificationUrl": "https://example.com", "queueRegion": "string", "sandboxSessionId": "example_id", "sandboxName": "Example Name", "workflowRunId": "example_id", "workflowName": "Example Name", "workflowStatus": "string", "stepRunId": "example_id", "workflowStepName": "Example Name", "workflowEventType": "string", "region": "string", "specVersion": "string", "contentType": "string", "rewriteDestinationHostname": "Example Name", "externalRewriteTargetHost": "string", "externalRewriteTargetPath": "string", "commitSha": "string", "reviewConclusion": "string", "pullRequestNumber": "string", "repositoryName": "Example Name", "repositoryOwner": "string", "reviewStatus": "string", "pullRequestState": "string", "triggeringTag": "string", "redirectLocation": "string", "microfrontendsResponseReason": "Customer requested refund", "microfrontendsMatchedPath": "string", "microfrontendsDefaultAppDeploymentId": "example_id", "microfrontendsDefaultAppProjectId": "example_id", "service": "string", "isPrefetchRequest": "string", "spendReportGroupBy": "string", "spendReportDatePart": "string", "providerAttemptCanonicalSlug": "example_id", "providerAttemptCredentialType": "example_id", "providerAttemptSuccess": "example_id", "providerAttemptStatusCode": "example_id", "providerAttemptTimeout": "example_id", "providerAttemptIsFinal": "example_id", "providerAttemptNumber": "example_id", "providerAttemptTotalInRequest": "100.00", "generationId": "example_id", "sessionId": "example_id", "contentCaptureStatus": "string", "contentCaptureInputs": "string", "contentCaptureOutputs": "string", "transcriptStatus": "string", "transcriptInputs": "string", "transcriptOutputs": "string", "providerAttemptError": "example_id", "providerAttemptSafetyIdentifier": "example_id", "providerAttemptDevSafetyIdentifier": "example_id", "providerAttemptRegion": "example_id", "providerAttemptModelIndex": "example_id", "toolCallType": "string", "toolCallProvider": "example_id", "toolCallSuccess": "string", "toolCallErrorType": "string", "toolCallStatusCode": "string", "environmentId": "example_id", "billableRegion": "string", "direction": "string", "networkTenancy": "string", "trafficSource": "string", "networkId": "example_id", "privatelinkEndpointId": "example_id", "privatelinkDnsName": "Example Name", "privatelinkIpAddress": "string", "timestamp": "2024-01-01T00:00:00Z" } ] } ``` ## Responses ### 200: No description Content-Type: `application/json` ```json { "type": "object", "required": [ "data", "query", "version" ], "properties": { "version": { "type": "number" }, "query": { "type": "object", "required": [ "limit", "since", "until" ], "properties": { "since": { "type": "string" }, "until": { "type": "string" }, "groupBy": { "type": "array", "items": {} }, "filter": { "type": "string" }, "limit": { "type": "number" } } }, "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "required": [ "timestamp" ] } }, { "type": "array", "items": { "type": "object", "required": [ "aiGatewayModelId", "aiModel", "aiModelType", "aiProvider", "appName", "asnId", "asnName", "attributes", "attributionEventName", "attributionTarget", "authMethod", "billableRegion", "blobOperationLevel", "blobOperationType", "botCategory", "botCategoryLegacy", "botCheckResult", "botName", "botVerified", "browserName", "cacheApi", "cacheCreation1hInputTokensCurrency", "cacheCreationInputTokensCurrency", "cacheHitLevel", "cacheHitState", "cacheHostname", "cacheOperation", "cachePath", "cacheReason", "cacheResult", "cacheTags", "cachedInputTokensCurrency", "cause", "clientIp", "clientIpCountry", "clientJa4Digest", "clientUserAgent", "codingAgent", "commitSha", "consumerGroup", "contentCaptureInputs", "contentCaptureOutputs", "contentCaptureStatus", "contentType", "costCurrency", "country", "dataCacheRegion", "deepAnalysisCheck", "deploymentId", "deviceType", "direction", "edgeNetworkRegion", "edgeType", "entryId", "entryItemId", "entryName", "entryRevalidateSeconds", "environment", "environmentId", "errorCode", "errorMessage", "eventData", "eventName", "eventType", "externalRewriteTargetHost", "externalRewriteTargetPath", "fetchIndex", "fetchType", "flagClientName", "flagEvaluationReason", "flagKey", "flagVariant", "flags", "functionDispatcher", "functionRegion", "functionStartType", "gatewayCostCurrency", "generationId", "hipaaRequested", "httpAccept", "httpStatus", "imageSource", "imageTransformationRegion", "inferenceEndpointSlug", "inferenceGeoRegion", "inferenceProviderRegion", "inferenceScope", "isAdditionalRequest", "isByok", "isPrefetchRequest", "isPrivateModel", "isRequestZdr", "isrAction", "isrCacheRegion", "keyId", "keyName", "marketCostCurrency", "messageId", "metricName", "microfrontendsDefaultAppDeploymentId", "microfrontendsDefaultAppProjectId", "microfrontendsMatchedPath", "microfrontendsResponseReason", "middlewareAction", "middlewareActionTarget", "moderationApplied", "networkId", "networkTenancy", "notificationUrl", "optimizedFormatMimeType", "optimizedQuality", "optimizedWidthPixels", "originHostname", "originPath", "originRoute", "osName", "pathType", "pathTypeVariant", "piiRedactionApplied", "pprState", "privatelinkDnsName", "privatelinkEndpointId", "privatelinkIpAddress", "projectId", "projectName", "provider", "providerAttemptCanonicalSlug", "providerAttemptCredentialType", "providerAttemptDevSafetyIdentifier", "providerAttemptError", "providerAttemptIsFinal", "providerAttemptModelIndex", "providerAttemptNumber", "providerAttemptRegion", "providerAttemptSafetyIdentifier", "providerAttemptStatusCode", "providerAttemptSuccess", "providerAttemptTimeout", "providerAttemptTotalInRequest", "pullRequestNumber", "pullRequestState", "queueName", "queueRegion", "quotaEntityId", "quotaEntityType", "quotaRequested", "reason", "redirectLocation", "referrerHostname", "referrerUrl", "region", "reportingProjectId", "reportingProjectName", "repositoryName", "repositoryOwner", "requestApi", "requestExtension", "requestHostname", "requestId", "requestMethod", "requestPath", "requestResolvedIp", "requestedInferenceRegion", "reviewConclusion", "reviewStatus", "rewriteDestinationHostname", "route", "ruleCategory", "runtime", "sandboxName", "sandboxSessionId", "sdkKeyEnvironment", "sdkKeyId", "servedSpeed", "serverActionName", "service", "sessionId", "skewProtection", "source", "sourceImage", "sourceImageHash", "sourceImageHostname", "sourceImagePathname", "specVersion", "spendAttribution", "spendReportDatePart", "spendReportGroupBy", "stepRunId", "storeId", "storeName", "surchargeCostCurrency", "tagName", "toolCallErrorType", "toolCallProvider", "toolCallStatusCode", "toolCallSuccess", "toolCallType", "trafficSource", "transcriptInputs", "transcriptOutputs", "transcriptStatus", "triggeringTag", "utmCampaign", "utmContent", "utmMedium", "utmSource", "utmTerm", "vdcOperationOrigin", "videoAspectRatio", "videoResolution", "virtualModelKind", "virtualModelSlug", "visitorId", "wafAction", "wafRuleId", "workflowEventType", "workflowName", "workflowRunId", "workflowStatus", "workflowStepName" ] } } ] } } } ``` ### 400: One of the provided values in the request query is invalid. ### 401: The request is not authorized. ### 402: No description ### 403: You do not have permission to access this resource. ### 410: No description --- ## Related - [web-analytics endpoints](/docs/rest-api#web-analytics) - [REST API overview](/docs/rest-api) - [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints) --- [View full sitemap](/docs/sitemap)