---
title: "Narrative of a visit"
method: GET
path: "/v1/projects/{projectId}/sessions/{sessionId}/narrative"
tags: ["Visits"]
---

# Narrative of a visit

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

## Request

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

A step-by-step account of a whole visit, up to 25 page views. Observed behavior only; it never states emotion or intent. The person behind the credential must hold the replay permission on the site (403 replay_required otherwise).

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.
- `sessionId` string, required: An identifier: 1 to 80 letters, digits, underscores or hyphens.

## Response `200`

The narrative.

- Narrative
  - `summary` string, required
  - `facts` object, required
    - `durationMs` integer, required
    - `activeMs` integer, required
    - `pages` string[], required
    - `device` 'desktop' | 'tablet' | 'mobile', required
    - `browser` string
    - `os` string
    - `referrer` string
    - `utmSource` string
    - `maxScrollPercent` number
    - `clicks` integer, required
    - `touch` boolean
    - `pileUps` integer, required
    - `pileUpsOnNonControls` integer: Pile-up episodes on an element that is not a link, button or other control. Absent when none.
    - `noShows` integer, required
    - `misfires` integer, required
    - `exitPage` string, required
  - `steps` object[], required
    - `atMs` integer, required
    - `clock` string, required
    - `kind` 'landed' | 'scrolled' | 'clicked' | 'snag' | 'error' | 'navigated' | 'resized' | 'idle' | 'left', required
    - `text` string, required
    - `recordingId` string, required: The page view the moment belongs to.
    - `offsetMs` integer, required: Position to seek to in that recording.
    - `selector` string
    - `label` string
    - `source` string: Source file and line behind the clicked element, such as `src/components/Pricing.tsx:42`. Present on click and snag steps when the site uses the Hoot Lens build plugin.
    - `interactive` false: False when the clicked element is not a link, button or other control. Present only on click and snag steps for such elements.
  - `omittedSteps` integer, required
  - `omittedPages` integer, required
  - `note` string
  - `annotations` object: The team's own notes and tags: free text a person wrote, never captured from visitors.

## Other responses

- `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)