---
title: "List visits"
method: GET
path: "/v1/projects/{projectId}/sessions"
tags: ["Visits"]
---

# List visits

`GET /v1/projects/{projectId}/sessions`

## Request

- Base URL: `https://hootlens-api-368877148687.us-east1.run.app`
- URL: `https://hootlens-api-368877148687.us-east1.run.app/v1/projects/{projectId}/sessions`
- Auth: HTTP bearer

Visits (page views stitched by the tag), newest first, each with a one-line summary. A visit is listed when any of its page views matches the filters.

Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).

## Path parameters

- `projectId` string, required: An identifier: 1 to 80 letters, digits, underscores or hyphens.

## Query parameters

- `cursor` string
- `limit` integer
- `path` string
- `group` string
- `locale` string
- `variant` string
- `tag` string
- `deviceClass` 'desktop' | 'tablet' | 'mobile'
- `minDurationMs` integer
- `signal` 'rage' | 'dead' | 'error'
- `controlled` 'exclude' | 'include' | 'only'
- `automated` 'exclude' | 'include' | 'only'
- `internal` 'exclude' | 'include' | 'only'
- `goal` string
- `element` string
- `utmSource` string
- `utmCampaign` string
- `referrer` string
- `browser` 'chrome' | 'safari' | 'firefox' | 'edge' | 'other'
- `os` 'windows' | 'macos' | 'ios' | 'android' | 'linux' | 'other'
- `newVisitor` 'true' | 'false'
- `segmentId` string: An identifier: 1 to 80 letters, digits, underscores or hyphens.
- `from` integer
- `to` integer

## Response `200`

A page of visits.

- SessionPage
  - `sessions` SessionSummary[], required
    - `sessionId` string, required: An identifier: 1 to 80 letters, digits, underscores or hyphens.
    - `startedAt` integer, required: Epoch milliseconds.
    - `endedAt` integer, required: Epoch milliseconds.
    - `pageCount` integer, required
    - `paths` string[], required
    - `groups` string[]
    - `locales` string[]
    - `device` 'desktop' | 'tablet' | 'mobile', required
    - `browser` 'chrome' | 'safari' | 'firefox' | 'edge' | 'other'
    - `os` 'windows' | 'macos' | 'ios' | 'android' | 'linux' | 'other'
    - `maxScrollPercent` number
    - `marks` ClickMark[]
      - `t` integer, required: Milliseconds from the start of the page view.
      - `k` 'click' | 'rage-click' | 'dead-click' | 'error-click', required
      - `y` number: Where the click landed down the document, 0 to 1.
    - `clickCount` integer, required
    - `rageClickCount` integer, required
    - `deadClickCount` integer, required
    - `errorClickCount` integer, required
    - `automated` boolean
    - `automationReasons` string[]
    - `internal` boolean: True when any page view of the visit was made by the site's own team.
    - `goals` object[]: The goals the visit converted, in goal order, under each goal's current definition.
      - `goalId` string, required: An identifier: 1 to 80 letters, digits, underscores or hyphens.
      - `name` string, required
    - `exitTo` string: Where the visit went when its last click left through a link: a same-site path, or another site's origin only.
    - `summary` string, required: One or two sentences describing the visit from observed behavior. Ends with the top snag when the visit has one.
    - `topSnag` object: The element with the most snag clicks in the visit. Absent when the visit had none, and for visits recorded before it was kept.
      - `kind` 'pile-up' | 'no-show' | 'misfire', required
      - `count` integer, required: The element's snag clicks of this kind in the visit.
      - `selector` string, required
      - `name` string: The name the team gave the element, when it has one.
      - `label` string: The most recent recorded label of the element.
      - `context` ElementContext: Short context recorded with a click. The strict preset records tag and region only.
        - `tag` string: Tag of the clicked element, such as div, li, p or img.
        - `region` string: The nearest region: a data-hoot-region, an ancestor data-hoot-id, a section with an id or aria-label, else the nearest landmark tag. At most 60 characters.
        - `heading` string: Text of the nearest h1 to h3 above the element. Full and balanced presets only; at most 60 characters.
        - `text` string: The element's own text, shortened. Full and balanced presets only; at most 60 characters.
      - `interactive` false: False when the element is not a link, button or other control.
  - `nextCursor` string: Pass back as cursor. Absent on the last page.

## Other responses

- `400`: The request fields are invalid.
- `401`: The credential is missing, expired or revoked.
- `403`: The credential or the person's permissions on the site do not permit this action.
- `404`: The site, or the record inside it, does not exist or the caller is not a member (a non-member cannot tell the two apart).
- `429`: A rate limit or a per-site limit was reached.

---

[API](https://skmtc.dev/hootlens/apis/hoot-lens-api.md) · [All operations](https://skmtc.dev/hootlens/apis/hoot-lens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hootlens/apis/hoot-lens-api/revisions/f64f8dc7b84e?raw)