Skip to content
Docs

Aggregates custom events

GEThttps://api.vercel.com/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.
Request
import { Vercel } from "@vercel/sdk";


const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});


async function run() {
  const result = await vercel.webAnalytics.aggregateEvents({
    projectId: "prj_XLKmu1DyR1eY7zq8UgeRKbA7yVLA",
    by: [
      "day",
      "eventName",
    ],
    since: "2024-09-01T00:00:00.000Z",
    until: "2024-09-08T00:00:00.000Z",
    limit: 3,
    filter: "eventData/plan eq 'pro'",
    teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
    slug: "my-team-url-slug",
  });


  console.log(result);
}


run();
Response
{
  "data": [
    {
      "browserName": "Example Name",
      "country": "string",
      "deviceType": "string",
      "environment": "string",
      "eventData": "string",
      "eventName": "Example Name",
      "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"
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Query parameters

projectIdstringRequired
The project identifier or the project name
byarrayRequired
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'.
sinceanyRequired
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.
untilanyRequired
Timestamp in milliseconds, or a valid Date string.
Selects data until (including) this date. Will be adjusted according to the desired time granularity.
limitintegerOptional
Number of distinct results, default to 10. Other results are grouped into "Others" group.
filterstringOptional
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.
teamIdstringOptional
The Team identifier to perform the request on behalf of.
slugstringOptional
The Team slug to perform the request on behalf of.

Response

200Success
dataobjectRequired2 variants
queryobjectRequired
versionnumberRequired

Errors

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