---
title: "Aggregates custom events"
method: GET
path: "/v1/query/web-analytics/events/aggregate"
tags: ["web-analytics"]
---

# Aggregates custom events

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

Counts custom events 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, 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'.
  - union
    - 'hour' | 'day' | 'week' | 'month' | 'year' | 'country' | 'deviceType' | 'environment' | 'requestPath' | 'referrerHostname' | 'osName' | 'browserName' | 'route' | 'utmSource' | 'utmMedium' | 'utmCampaign' | 'utmContent' | 'utmTerm' | 'eventName' | 'flags' | 'eventData'
    - 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, eventName. JSON dimensions filtered by key: flags/<name>, eventData/<property>, 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
- `slug` string

## Response `200`

- object
  - `version` number, required
  - `query` object, required
    - `since` string, required
    - `until` string, required
    - `groupBy` union[]
      - union
        - string
        - 'browserName' | 'country' | 'deviceType' | 'environment' | 'eventData' | 'eventName' | 'flags' | 'osName' | 'referrerHostname' | 'requestPath' | 'route' | 'utmCampaign' | 'utmContent' | 'utmMedium' | 'utmSource' | 'utmTerm'
    - `filter` string
    - `limit` number, required
  - `data` union, required
    - object[]
      - `projectId` string
      - `country` string
      - `deviceType` string
      - `environment` string
      - `requestPath` string
      - `referrerHostname` string
      - `osName` string
      - `browserName` string
      - `route` string
      - `utmSource` string
      - `utmMedium` string
      - `utmCampaign` string
      - `utmContent` string
      - `utmTerm` string
      - `flags` string
      - `errorMessage` string
      - `entryRevalidateSeconds` string
      - `projectName` string
      - `deploymentId` string
      - `pathType` string
      - `pathTypeVariant` string
      - `requestHostname` string
      - `requestResolvedIp` string
      - `requestMethod` string
      - `requestExtension` string
      - `requestId` string
      - `requestApi` string
      - `referrerUrl` string
      - `serverActionName` string
      - `httpStatus` string
      - `errorCode` string
      - `source` string
      - `edgeType` string
      - `reason` string
      - `edgeNetworkRegion` string
      - `functionRegion` string
      - `imageTransformationRegion` string
      - `dataCacheRegion` string
      - `cause` string
      - `runtime` string
      - `provider` string
      - `isrCacheRegion` string
      - `isrAction` string
      - `cacheResult` string
      - `cacheOperation` string
      - `cacheHostname` string
      - `cachePath` string
      - `cacheHitState` string
      - `cacheHitLevel` string
      - `cacheApi` string
      - `cacheReason` string
      - `clientIp` string
      - `clientIpCountry` string
      - `clientUserAgent` string
      - `httpAccept` string
      - `clientJa4Digest` string
      - `asnId` string
      - `asnName` string
      - `botName` string
      - `botCategory` string
      - `botCategoryLegacy` string
      - `botVerified` string
      - `botCheckResult` string
      - `deepAnalysisCheck` string
      - `wafAction` string
      - `wafRuleId` string
      - `skewProtection` string
      - `functionStartType` string
      - `functionDispatcher` string
      - `isAdditionalRequest` string
      - `originHostname` string
      - `originPath` string
      - `originRoute` string
      - `fetchType` string
      - `fetchIndex` string
      - `imageSource` string
      - `sourceImage` string
      - `sourceImagePathname` string
      - `sourceImageHostname` string
      - `sourceImageHash` string
      - `optimizedQuality` string
      - `optimizedWidthPixels` string
      - `optimizedFormatMimeType` string
      - `vdcOperationOrigin` string
      - `entryName` string
      - `entryId` string
      - `entryItemId` string
      - `tagName` string
      - `cacheTags` string
      - `storeId` string
      - `storeName` string
      - `blobOperationType` string
      - `blobOperationLevel` string
      - `visitorId` string
      - `eventName` string
      - `attributionTarget` string
      - `attributionEventName` string
      - `metricName` string
      - `attributes` string
      - `flagKey` string
      - `flagVariant` string
      - `flagEvaluationReason` string
      - `flagClientName` string
      - `sdkKeyId` string
      - `sdkKeyEnvironment` string
      - `reportingProjectId` string
      - `reportingProjectName` string
      - `eventData` string
      - `middlewareAction` string
      - `middlewareActionTarget` string
      - `aiModel` string
      - `aiGatewayModelId` string
      - `aiProvider` string
      - `aiModelType` string
      - `servedSpeed` string
      - `virtualModelSlug` string
      - `virtualModelKind` string
      - `inferenceEndpointSlug` string
      - `inferenceScope` string
      - `inferenceGeoRegion` string
      - `inferenceProviderRegion` string
      - `requestedInferenceRegion` string
      - `costCurrency` string
      - `marketCostCurrency` string
      - `cachedInputTokensCurrency` string
      - `cacheCreationInputTokensCurrency` string
      - `cacheCreation1hInputTokensCurrency` string
      - `surchargeCostCurrency` string
      - `gatewayCostCurrency` string
      - `keyId` string
      - `keyName` string
      - `authMethod` string
      - `appName` string
      - `codingAgent` string
      - `isByok` string
      - `isPrivateModel` string
      - `isRequestZdr` string
      - `hipaaRequested` string
      - `quotaRequested` string
      - `quotaEntityId` string
      - `quotaEntityType` string
      - `videoResolution` string
      - `videoAspectRatio` string
      - `piiRedactionApplied` string
      - `moderationApplied` string
      - `queueName` string
      - `consumerGroup` string
      - `messageId` string
      - `eventType` string
      - `notificationUrl` string
      - `sandboxSessionId` string
      - `sandboxName` string
      - `workflowRunId` string
      - `workflowName` string
      - `workflowStatus` string
      - `stepRunId` string
      - `workflowStepName` string
      - `workflowEventType` string
      - `region` string
      - `specVersion` string
      - `contentType` string
      - `rewriteDestinationHostname` string
      - `externalRewriteTargetHost` string
      - `externalRewriteTargetPath` string
      - `commitSha` string
      - `reviewConclusion` string
      - `pullRequestNumber` string
      - `repositoryName` string
      - `repositoryOwner` string
      - `reviewStatus` string
      - `pullRequestState` string
      - `triggeringTag` string
      - `redirectLocation` string
      - `microfrontendsResponseReason` string
      - `microfrontendsMatchedPath` string
      - `microfrontendsDefaultAppDeploymentId` string
      - `microfrontendsDefaultAppProjectId` string
      - `service` string
      - `isPrefetchRequest` string
      - `spendReportGroupBy` string
      - `spendReportDatePart` string
      - `providerAttemptCanonicalSlug` string
      - `providerAttemptCredentialType` string
      - `providerAttemptSuccess` string
      - `providerAttemptStatusCode` string
      - `providerAttemptTimeout` string
      - `providerAttemptIsFinal` string
      - `providerAttemptNumber` string
      - `providerAttemptTotalInRequest` string
      - `generationId` string
      - `sessionId` string
      - `contentCaptureStatus` string
      - `contentCaptureInputs` string
      - `contentCaptureOutputs` string
      - `transcriptStatus` string
      - `transcriptInputs` string
      - `transcriptOutputs` string
      - `providerAttemptError` string
      - `providerAttemptSafetyIdentifier` string
      - `providerAttemptDevSafetyIdentifier` string
      - `providerAttemptRegion` string
      - `providerAttemptModelIndex` string
      - `toolCallType` string
      - `toolCallProvider` string
      - `toolCallSuccess` string
      - `toolCallErrorType` string
      - `toolCallStatusCode` string
      - `environmentId` string
      - `billableRegion` string
      - `direction` string
      - `networkTenancy` string
      - `trafficSource` string
      - `networkId` string
      - `privatelinkEndpointId` string
      - `privatelinkDnsName` string
      - `privatelinkIpAddress` string
      - `timestamp` string, date-time, required
    - object[]
      - `projectId` string, required
      - `country` string, required
      - `deviceType` string, required
      - `environment` string, required
      - `requestPath` string, required
      - `referrerHostname` string, required
      - `osName` string, required
      - `browserName` string, required
      - `route` string, required
      - `utmSource` string, required
      - `utmMedium` string, required
      - `utmCampaign` string, required
      - `utmContent` string, required
      - `utmTerm` string, required
      - `flags` string, required
      - `errorMessage` string, required
      - `entryRevalidateSeconds` string, required
      - `projectName` string, required
      - `deploymentId` string, required
      - `pathType` string, required
      - `pathTypeVariant` string, required
      - `requestHostname` string, required
      - `requestResolvedIp` string, required
      - `requestMethod` string, required
      - `requestExtension` string, required
      - `requestId` string, required
      - `requestApi` string, required
      - `referrerUrl` string, required
      - `serverActionName` string, required
      - `httpStatus` string, required
      - `errorCode` string, required
      - `source` string, required
      - `edgeType` string, required
      - `reason` string, required
      - `edgeNetworkRegion` string, required
      - `functionRegion` string, required
      - `imageTransformationRegion` string, required
      - `dataCacheRegion` string, required
      - `cause` string, required
      - `runtime` string, required
      - `provider` string, required
      - `isrCacheRegion` string, required
      - `isrAction` string, required
      - `cacheResult` string, required
      - `cacheOperation` string, required
      - `cacheHostname` string, required
      - `cachePath` string, required
      - `cacheHitState` string, required
      - `cacheHitLevel` string, required
      - `cacheApi` string, required
      - `cacheReason` string, required
      - `clientIp` string, required
      - `clientIpCountry` string, required
      - `clientUserAgent` string, required
      - `httpAccept` string, required
      - `clientJa4Digest` string, required
      - `asnId` string, required
      - `asnName` string, required
      - `botName` string, required
      - `botCategory` string, required
      - `botCategoryLegacy` string, required
      - `botVerified` string, required
      - `botCheckResult` string, required
      - `deepAnalysisCheck` string, required
      - `wafAction` string, required
      - `wafRuleId` string, required
      - `skewProtection` string, required
      - `functionStartType` string, required
      - `functionDispatcher` string, required
      - `isAdditionalRequest` string, required
      - `originHostname` string, required
      - `originPath` string, required
      - `originRoute` string, required
      - `fetchType` string, required
      - `fetchIndex` string, required
      - `imageSource` string, required
      - `sourceImage` string, required
      - `sourceImagePathname` string, required
      - `sourceImageHostname` string, required
      - `sourceImageHash` string, required
      - `optimizedQuality` string, required
      - `optimizedWidthPixels` string, required
      - `optimizedFormatMimeType` string, required
      - `vdcOperationOrigin` string, required
      - `entryName` string, required
      - `entryId` string, required
      - `entryItemId` string, required
      - `tagName` string, required
      - `cacheTags` string, required
      - `storeId` string, required
      - `storeName` string, required
      - `blobOperationType` string, required
      - `blobOperationLevel` string, required
      - `visitorId` string, required
      - `eventName` string, required
      - `attributionTarget` string, required
      - `attributionEventName` string, required
      - `metricName` string, required
      - `attributes` string, required
      - `flagKey` string, required
      - `flagVariant` string, required
      - `flagEvaluationReason` string, required
      - `flagClientName` string, required
      - `sdkKeyId` string, required
      - `sdkKeyEnvironment` string, required
      - `reportingProjectId` string, required
      - `reportingProjectName` string, required
      - `eventData` string, required
      - `middlewareAction` string, required
      - `middlewareActionTarget` string, required
      - `aiModel` string, required
      - `aiGatewayModelId` string, required
      - `aiProvider` string, required
      - `aiModelType` string, required
      - `servedSpeed` string, required
      - `virtualModelSlug` string, required
      - `virtualModelKind` string, required
      - `inferenceEndpointSlug` string, required
      - `inferenceScope` string, required
      - `inferenceGeoRegion` string, required
      - `inferenceProviderRegion` string, required
      - `requestedInferenceRegion` string, required
      - `costCurrency` string, required
      - `marketCostCurrency` string, required
      - `cachedInputTokensCurrency` string, required
      - `cacheCreationInputTokensCurrency` string, required
      - `cacheCreation1hInputTokensCurrency` string, required
      - `surchargeCostCurrency` string, required
      - `gatewayCostCurrency` string, required
      - `keyId` string, required
      - `keyName` string, required
      - `authMethod` string, required
      - `appName` string, required
      - `codingAgent` string, required
      - `isByok` string, required
      - `isPrivateModel` string, required
      - `isRequestZdr` string, required
      - `hipaaRequested` string, required
      - `quotaRequested` string, required
      - `quotaEntityId` string, required
      - `quotaEntityType` string, required
      - `videoResolution` string, required
      - `videoAspectRatio` string, required
      - `piiRedactionApplied` string, required
      - `moderationApplied` string, required
      - `queueName` string, required
      - `consumerGroup` string, required
      - `messageId` string, required
      - `eventType` string, required
      - `notificationUrl` string, required
      - `sandboxSessionId` string, required
      - `sandboxName` string, required
      - `workflowRunId` string, required
      - `workflowName` string, required
      - `workflowStatus` string, required
      - `stepRunId` string, required
      - `workflowStepName` string, required
      - `workflowEventType` string, required
      - `region` string, required
      - `specVersion` string, required
      - `contentType` string, required
      - `rewriteDestinationHostname` string, required
      - `externalRewriteTargetHost` string, required
      - `externalRewriteTargetPath` string, required
      - `commitSha` string, required
      - `reviewConclusion` string, required
      - `pullRequestNumber` string, required
      - `repositoryName` string, required
      - `repositoryOwner` string, required
      - `reviewStatus` string, required
      - `pullRequestState` string, required
      - `triggeringTag` string, required
      - `redirectLocation` string, required
      - `microfrontendsResponseReason` string, required
      - `microfrontendsMatchedPath` string, required
      - `microfrontendsDefaultAppDeploymentId` string, required
      - `microfrontendsDefaultAppProjectId` string, required
      - `service` string, required
      - `isPrefetchRequest` string, required
      - `spendReportGroupBy` string, required
      - `spendReportDatePart` string, required
      - `providerAttemptCanonicalSlug` string, required
      - `providerAttemptCredentialType` string, required
      - `providerAttemptSuccess` string, required
      - `providerAttemptStatusCode` string, required
      - `providerAttemptTimeout` string, required
      - `providerAttemptIsFinal` string, required
      - `providerAttemptNumber` string, required
      - `providerAttemptTotalInRequest` string, required
      - `generationId` string, required
      - `sessionId` string, required
      - `contentCaptureStatus` string, required
      - `contentCaptureInputs` string, required
      - `contentCaptureOutputs` string, required
      - `transcriptStatus` string, required
      - `transcriptInputs` string, required
      - `transcriptOutputs` string, required
      - `providerAttemptError` string, required
      - `providerAttemptSafetyIdentifier` string, required
      - `providerAttemptDevSafetyIdentifier` string, required
      - `providerAttemptRegion` string, required
      - `providerAttemptModelIndex` string, required
      - `toolCallType` string, required
      - `toolCallProvider` string, required
      - `toolCallSuccess` string, required
      - `toolCallErrorType` string, required
      - `toolCallStatusCode` string, required
      - `environmentId` string, required
      - `billableRegion` string, required
      - `direction` string, required
      - `networkTenancy` string, required
      - `trafficSource` string, required
      - `networkId` string, required
      - `privatelinkEndpointId` string, required
      - `privatelinkDnsName` string, required
      - `privatelinkIpAddress` string, 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.
- `410`

---

[API](https://skmtc.net/vercel/apis/api.md) · [All operations](https://skmtc.net/vercel/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vercel/api/versions/61d1ba3f6dac/schema)