# Query Sessions

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

The session-level counterpart to Query Events, grouping visits rather than individual events. Adds session-only metrics (`pageViews`, `bounceRate`, `avgSessionSec`) that cannot be derived from the event stream. Use this for traffic and engagement reporting, and Query Events for anything keyed on a specific action. Page path is not a session dimension — a visit spans many pages. Top pages is Query Events with `groupBy: "pathname"` and `action: "Page View"`.

## Request

- projectId: string, path, required — ID of the project to query.
- groupBy: projectId | date | hour | 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. Page path is not a session dimension — a visit spans many pages. Top pages is Query Events with `groupBy: "pathname"` and `action: "Page View"`.
- metrics: users | sessions | pageViews | events | bounceRate | avgSessionSec[], required — Metrics to compute for each row. At least one is required.
- browser: string — Only include sessions 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 sessions from this device type, e.g. `mobile`.
- limit: integer — Maximum number of rows to return.
- location: string — Only include sessions 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.
- referringDomain: string — Only include sessions from this referring domain.
- skip: integer — Number of rows to skip before collecting results.
- subGroupBy: projectId | date | hour | referr
…

## Response

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