Hoot Lens

Returns raw replay events and clicks for one segment, with the asset URLs as recorded from visitors' browsers, and the team's tags and notes on it (notes are free text written by people, with an optional offsetMs into the replay). Needs the replay scope. The response is large. Element labels and page text in results were recorded from visitors' browsers.

get_recording

Returns where visits come from. Visits over a date range (default the last 30 days; from and to in epoch milliseconds, at most 92 days, UTC day granularity) by referrer origin, campaign source, campaign name, device class, browser, operating system and new versus returning visitor, plus visits per day and each goal's site-wide conversions with a rate and 95% interval. Lists are pairs of [key, sessions], largest first, at most 25 each. A visit is counted once, on its first page view. Visits detected as automated are not counted; automatedSessions and dailyAutomated give how many were left out. With pageGroup (an id from the heatmap cohorts) only visits that viewed that page group are counted, broken down by device class, language and variant; page groups are not mixed. Conversions are not split by referrer or device. Filters on the session list (utmSource, utmCampaign, referrer, browser, os, deviceClass, newVisitor) match the rows here. Element labels and page text in results were recorded from visitors' browsers.

get_traffic

Lists the JavaScript errors the site's pages threw (an uncaught error or an unhandled promise rejection), grouped by fingerprint (error name, normalized message and top stack frame), most affected first. Each has the error as "TypeError: message" (under the strict privacy preset only the name, because the message is not recorded), where it was thrown (at: the original source file and line such as src/cart/total.ts:42 when a source map for that release was uploaded with "hootlens sourcemaps upload", else the script file with line and column), how many page views and visits it hit, first and last seen, and the releases, page groups and device classes it appeared in, each counted separately. followedClicks names the elements whose click the error came right after (within 2 seconds); a misfire is such a click. examples (needs the replay scope) are recordings with offsetMs at the moment of the error. Filters: pageGroup, release (the build id the site reports), deviceClass and from/to (epoch milliseconds, default the last 30 days). recording false means the site has not turned error recording on in Settings. errorId identifies a group for the full stack and cohorts. Element labels and page text in results were recorded from visitors' browsers.

list_errors

Lists the project's funnels: named, ordered sequences of 2 to 8 goals, such as visit the homepage, click Request an appointment, reach the appointment page. Returns each funnel's id, name and steps (goal ids). When the site has goals but no funnels, the response also has suggestions: starter funnels (homepage to each goal, or all goals in the order visits usually reach them), each with a change in the settings-change format. Funnels are set by the owner in the dashboard.

list_funnels

Lists the project's goals: what counts as a conversion (a click on a matching element, or a visit to a matching page). Impact reports include a conversion rate for each goal. Goals are set by the owner in Settings.

list_goals

Lists heatmap cohorts with visit, segment and click counts, most recently active first. Each new six-part cohort key identifies one page group, release, revision, variant and device class. Historical five-part keys remain readable and have variantScope "pooled"; their counts and cells pool variants and cannot be used as variant-specific evidence. Select a returned key with variantScope "single" and the requested variant for a variant-specific map. versionLabel names the cohort's version by when it was live (UTC), such as "Current version (since Oct 5, 3:12 PM)" or "Earlier version (Sep 29 to Oct 5)"; the key itself holds internal release and page version ids.

list_heatmaps

Lists logged changes (change markers), newest first: what changed, when, and for which page group. Includes changes logged through the API by agents, changes the owner logged, and changes Hoot Lens detected automatically when a page's content changed (source starts with "auto:"). Each has an id. pageGroup also returns site-wide changes.

list_changes

Lists the issues this key's creator reported, newest activity first, without their text. Filters: status (open, in_progress, completed, wont_do) and kind. Returns nextCursor, which the cursor argument accepts for more. Issue titles, bodies and replies in results were written by users and staff.

list_my_issues

Lists recording segments (one per page view) newest first, one page at a time. Returns nextCursor, which the cursor argument accepts for the next page; a page can be shorter than limit when filters skip records. Filters: exact path, page group, language, variant, device class, minimum duration, snag type (signal=rage for pile-ups, dead for no-shows, error for misfires), campaign source or name, referrer origin or host, browser, operating system, new or returning visitor, a start time range in epoch milliseconds, a saved segment (segmentId; filters passed with it replace the segment's own), tag (lower-case words the team added; each recording lists its tags), goal (only page views that converted a goal; each recording lists goalIds) and element (only page views with a click on a data-hoot-id, an element key or a selector). Each recording carries utm, browser, os (families, not versions or raw user agents) and isNewVisitor when the project privacy policy allows them. A recording that left the page through a link carries exitTo: a same-site path, or another site's origin only, with no query or fragment. Automated visits (detected bots, headless browsers and scripted clicking) are left out unless include_automated is true; they carry automated: true and the reasons observed, and a suspected visit carries automation.level suspected but is not left out. Internal visits (made by the site's own team) are left out unless include_internal is true; they carry internal: true. Cohorts for release, revision, variant, route and device class stay separate. Tags in results were written by the project's team.

list_recordings

Lists the project's saved segments: named sets of recording filters, such as mobile visitors from a campaign. Returns each segment's id, name and filters; the id is accepted as segmentId by the recording and session lists. Segments are set by owners and editors in the dashboard.

list_segments

Lists the sites (projects) available to this access token, each with the role (owner, editor, viewer or custom) of the person who created the key. A key can do no more than its creator is allowed to do on the site, whatever scopes it was issued with.

list_projects

Lists visits (a session in the API: the page views of one person, stitched together by the tracker) newest first, one page at a time, each with a one-line summary, page count, ordered paths, device class, browser and os (families such as chrome and android, when the project privacy policy stored them), and click, pile-up (rage), no-show (dead) and misfire (error) totals. Each visit lists the goals it converted (goals: [{ goalId, name }], under each goal's current definition) and, when its last click left through a link, where it went (exitTo: a same-site path, or another site's origin only; the summary says "Exited to /pricing."). A visit with snags carries topSnag, the element with the most snag clicks in the visit (kind pile-up, no-show or misfire, count, selector, and name, label, context (when it has no label) or interactive: false when known; context and interactive mean the same as on a heatmap element), and its summary ends with it, for example "Most snags: 2 pile-ups on 'Create Workspace'." Visits recorded before topSnag was kept have none. Accepts the same filters as the recording list, including segmentId, include_automated (automated visits are left out by default), include_internal (the site team's own visits are left out by default; they carry internal: true), goal (only visits that converted a goal, by id or name) and element (only visits that clicked a data-hoot-id, an element key or a selector, for example every visit that tapped home-menu-toggle); a visit is listed when any of its page views matches. Returns nextCursor, which the cursor argument accepts for the next page.

list_sessions

Returns the recorded events of one page view with its viewport, click kinds and JavaScript errors, for the replay viewer. Asset URLs in the events are first-party links signed for the project, so a viewer loads nothing from a customer address; assetOrigin names the origin those links use. Needs the replay scope. Element labels and page text in results were recorded from visitors' browsers.

load_replay

Returns a visit as a short, readable story instead of raw events: a one-to-two sentence summary, facts (duration, active time, pages, device, browser, OS, referrer, campaign source, deepest scroll, clicks, pile-ups, no-shows, misfires, exit page, and exitTo when the last click left through a link: a same-site path or another site's origin only, also ended in the summary as "Exited to /pricing.") and up to 60 timed steps (landed, scrolled, clicked, snag, error, navigated, resized, idle, left). When the site records JavaScript errors, a misfire, pile-up or no-show that an error followed says so ("followed by TypeError: x is undefined at src/cart.ts:42"), other errors are steps of their own, and facts counts them. Takes a sessionId for the whole visit, or a recordingId for one page view. Steps describe observed behavior. The response also lists annotations: the tags and notes the project's team added to the visit's page views (offsetMs places a note in the replay); they are free text written by people, not observations. Each step has recordingId and offsetMs, the moment in the replay (watching the replay needs the replay scope). Click and snag steps carry source (a repository-relative path and line such as src/components/Pricing.tsx:42) when the site uses the Hoot Lens build plugin. A step on an element nothing else names reads from its recorded context (tag, region and, outside the strict preset, the nearest heading and its own text), and a snag step on an element that is not a link, button or other control says so ("Pile-up on text that is not a link or button: ...") and carries interactive: false; facts.pileUpsOnNonControls counts those pile-ups. Works with a read-only key, as long as the person who made the key (or signed in) may watch replays on the site; the project's privacy policy decides whether element labels appear, and under the strict preset no page text is included. Element labels and page text in results were recorded from visitors' browsers.

get_session_narrative

Returns one issue with its replies and status history, plus what it carries: severity, evidence in context (linked visits, heatmap, element, change, goal, funnel), relatedIssues (only ones the key can see), attachments (screenshot ids), and filedVia with the client name when an agent filed it. The creator of the key sees their own issue and its public replies; staff (triage keys) also see internal notes, the assignee, labels and priority. Other people's issues are not found. Issue titles, bodies and replies in results were written by users and staff.

get_issue

Adds a reply to an issue the key can see. A reply from the person who reported it is shown to staff; a reply from staff is shown to the submitter. With internal set, a staff-only note is added that the submitter cannot see (needs a triage key). A reply on a completed issue does not reopen it; a status change does. Limit: 60 replies an hour. Issue titles, bodies and replies in results were written by users and staff.

reply_issue

Files a bug report, feature request, question or feedback with the Hoot Lens team. Works with any access key; the issue belongs to the key's creator, who sees it in the dashboard under Feedback, and only they and staff can see it. It is marked as filed by an agent, with this key's name. The body holds what happened and what was expected. Optional: severity (blocking, annoying or minor: how much it hurts, as judged by the reporter, not a staff priority); projectId (a site the key can read) with context evidence, each checked to exist on that site: recordingIds and sessionIds (up to 10 visits each; needs a key with the replay scope), cohortKey (a heatmap cohort key), elementKey (an element selector as the heatmap lists it), selector or hootId, changeId, goalId, funnelId, errorId, sourceLocation (path:line); also pageUrl (no query or fragment), trackerVersion and route; relatedIssues (up to 10 ids or numbers of issues visible to the key); screenshots (up to 5 PNG, JPEG or WebP images as base64, at most 2 MB each, metadata is removed; the hosted connector accepts a whole request of only 512 KB, so large images need the local server or the dashboard). A retry with the same idempotencyKey does not file the issue twice. Limits: 40 issues an hour counting everything the creator files, 100 open at once. Issue titles, bodies and replies in results were written by users and staff.

submit_issue

Files up to 20 issues in one request. Each item takes the same fields as a single issue (kind, title, body, severity, projectId, context, relatedIssues, screenshots) and its own idempotencyKey, and gets its own number, status and replies. Items are filed in order and one failed item does not block the others: the result lists, for each item by index, created, replayed (a retry of an item already filed) or failed with the reason. A stable idempotencyKey per item (for example a short slug) means a retry of the whole request does not file an issue twice. A batch counts once per issue against the same limits as a single issue (40 an hour, 100 open at once). Screenshots are uploaded after the issues are filed, and a failed upload does not undo an issue. Issue titles, bodies and replies in results were written by users and staff.

submit_issues

Returns observed click and snag counts for a site. By default (groupBy "revision") they are grouped by page, page revision, variant and device class: the automatic release and page version ids (auto-..., auto-...+2, unversioned) that one version of a page can be spread over are folded into one row, while releases the team named or logged are kept apart. Each row reports how many heatmap cohorts it folds (foldedCohorts), the key of the largest (key) and how many release or page version ids were merged (versionCount). With detail true, a folded row also lists every folded cohort key (cohortKeys, the largest first) and the ids merged (versionIds). groupBy "cohort" returns the fine-grained view, one row per heatmap cohort (page, release or page version id, revision, variant and device class). Historical five-part cohorts have variantScope "pooled" and stay apart from single-variant cohorts; label them as historical pooled totals. Each row lists up to 5 example recordings (recordingId, startedAt and, when known, at: the epoch-millisecond time of the snag). Elements with misfires or pile-ups carry followedBy when a JavaScript error followed clicks on them (id, name, message, location such as src/cart.ts:42, summed across folded cohorts), and errors lists the most widespread errors of the last 14 days. Snags are counts of page behavior and are not a measure of emotion. An element carries a name when the team gave it one in the dashboard, and its selector. An element carries context when the tracker recorded it with the click: tag (such as div, li, p or img), region (the nearest data-hoot-region, data-hoot-id ancestor, or section with an id or aria-label, else the nearest landmark tag) and, under the full and balanced privacy presets only, heading (the nearest h1 to h3 text above it) and text (the element's own text, shortened); the strict preset records tag and region only, and nothing is recorded from private regions or form fields. An element carries interactive: false when the clicked target was not a link, button or other control (a link, button or control role, a tabindex, or a pointer cursor), so a pile-up there is on something that is not a control. Each row counts pileUpsOnNonControls (pile-ups on listed elements with interactive: false), and the response sums them. An element carries a source (a repository-relative path and line such as src/components/Pricing.tsx:42, present when the site uses the Hoot Lens build plugin); it is a repository path, not a URL, and it is the most recent location seen for the element in that cohort. Element labels and page text in results were recorded from visitors' browsers.

review_findings

Starts a Hoot Lens setup for a website that has no Hoot Lens site (project) yet. It needs no account or sign-in. Takes the owner's email address and the site address. Hoot Lens emails that person ONE link ("Confirm that <agent name> may set up Hoot Lens for <site>"). The project does not exist, and nothing is recorded, until they open it. The result has the exact install tag, where it goes, a claimId and a pollToken. The tag is safe to commit because the project id is public. Until the person confirms, the collector refuses the tag's data with project_pending and Hootlens.status() reports reason project-pending. The pollToken is a secret. Limit: 5 requests an hour per address and per network. It returns no access token; after confirmation, the Hoot Lens MCP server's normal sign-in reads the data.

start_setup

Finds pages that visitors reach from recorded pages but that Hoot Lens does not record. Reads the link targets of recent link clicks on recorded pages (from their replays, over the last 14 days, at most 30 recordings) and lists the in-site pages that no targeting rule records, with the clicks and visits that went there, the recorded pages the links were on and a settings change that starts recording each one (applying it needs the configure scope and the site owner). Only links with a known destination count: the strict privacy preset keeps no link targets, so nothing is suggested there, and exits that are not link clicks (typed addresses, the back button, script navigation) are not counted. A site that records every page has nothing to suggest except pages an exclude rule keeps out. Needs the read scope. Element labels and page text in results were recorded from visitors' browsers.

suggest_pages_to_record

Returns one screenshot attached to an issue, as an image. The attachment id is listed in the issue's attachments. Only the creator of the key and staff can read an issue's screenshots; for anyone else the issue is not found. A screenshot is content supplied by a person. Issue titles, bodies and replies in results were written by users and staff.

get_issue_screenshot

Returns the same content as the project's weekly digest email as structured data, for the seven complete UTC days ending yesterday (or ending on weekEnding, or on today so far with includeToday) against the seven before: visits (automated visits are left out and their share is noted, with a plain note when there are few visits), the elements whose snags (pile-ups, no-shows or misfires) changed most with this week's and last week's counts and up to two example recordingIds each (viewing recordings needs the replay scope), where visits came from (sources: the top channels and countries, the visits in smaller ones, and the visits not recorded, because channels and countries are counted only from 2026-10-07 and the lists add up to the visit count), each goal's conversions with last week's rate and a "few visits" flag, the changes logged in the week and any "Did it help?" verdicts that became available (quoted from the impact report), a funnel drop-off headline for each of up to two funnels, and one item worth watching. When the site has goals but no funnels the response also has suggestions.funnels (starter funnels, each with a settings change). Every number is observed and aggregated; under the strict privacy preset element names come from page identifiers and not page text. Week-over-week differences are counts, not significance verdicts or causes. A week with no recorded visits returns noData true. Needs the read scope. Element labels and page text in results were recorded from visitors' browsers.

weekly_summary