# Query Events

POST /api/v2/projects/{projectId}/analytics/query-events

The general-purpose event reporting query. Pick a dimension to group by, the metrics to compute (`users`, `sessions`, `events`), and any filters, and it returns one aggregated row per group: a time series with `groupBy: "date"`, a top-pages table with `groupBy: "pathname"`, and so on. Dates are read in `timeZone` (the signed-in user's local zone on the dashboard, otherwise UTC).

## Request

- projectId: string, path, required — ID of the project to query.
- groupBy: projectId | date | hour | action | href | pathname | referrer | referringDomain | device | browser | location | utmSource | utmMedium | utmCampaign | utmTerm | utmContent | utmAdId, required — Dimension to aggregate by. One row comes back per distinct value. Use `date` or `hour` for a time series.
- metrics: users | sessions | events[], required — Metrics to compute for each row. At least one is required.
- action: string — Only include events with this action name, e.g. `Page View`.
- browser: string — Only include events from this browser, e.g. `Chrome`.
- dateFrom: string — Start of the window as a `YYYY-MM-DD` date, inclusive. Interpreted in `timeZone` (the signed-in user's local zone on the dashboard, otherwise UTC).
- dateTo: string — End of the window as a `YYYY-MM-DD` date, inclusive. Interpreted in `timeZone` (the signed-in user's local zone on the dashboard, otherwise UTC).
- device: string — Only include events from this device type, e.g. `mobile`.
- href: string — Only include events on this full URL.
- limit: integer — Maximum number of rows to return.
- location: string — Only include events from this country name.
- orderBy: string — Column to sort by: either `groupBy` or one of the requested `metrics`.
- orderDir: ASC | DESC — Sort direction. Ignored unless `orderBy` is set.
- pathname: string — Only include events on this path, e.g. `/pricing`.
- referrer: string — Only include events with this exact referrer URL.
- referringDomain: string — Only include events from this referring 
…

## Response

- 200: Successful response
  - data: object[], required
    - groupBy: string, required
    - events: number
    - sessions: number
    - subGroupBy: string
    - users: number
  - meta: object[], required
    - name: string, required
    - type: string, required
  - rows: number, required
  - rows_before_limit_at_least: number, required
  - statistics: object, required
    - bytes_read: number, required
    - elapsed: number, required
    - rows_read: number, required
- 400: Invalid input data
- 401: Authorization not provided
- 403: Insufficient access
- 500: Internal server error