---
title: "Narrative of one page view"
method: GET
path: "/v1/projects/{projectId}/recordings/{id}/narrative"
tags: ["Recordings"]
---

# Narrative of one page view

`GET /v1/projects/{projectId}/recordings/{id}/narrative`

## Request

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

A step-by-step account of one page view built from observed behavior: scrolls, clicks and snags (pile-ups, no-shows, misfires). Under the strict privacy preset it contains no page text. It also lists the team's own notes and tags. 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.
- `id` 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)