canonical: https://jentic.com/apis/hootlens.com/hootlens

# Hoot Lens API

The Hoot Lens API records website interaction evidence for the sites you add and returns it as visits, recordings, heatmaps, goals, funnels, and change impact. It reads session recordings and their narratives, heatmap cohorts and sampled clicks, traffic and weekly trends, and the measured impact of the changes you log. Use it to read observed on-site behavior and tie product changes to their effect, from an app or an agent.

## For AI agents

Read website behavior evidence for your sites: visits, session recordings, heatmaps, traffic trends, goals, funnels, and the measured impact of changes you log.

## Scope

Does not run A/B test variants, serve ads, or manage a tag container. Use for reading on-site behavior evidence such as visits, recordings, heatmaps, goals, and funnels only.

## Capabilities

- List the sites you track and read each site's install status
- Read session recordings and the narrative of a page view or visit
- Pull heatmap cohorts and their sampled clicks for a site
- Read visits, traffic, weekly trends, and weekly summaries
- Define goals and funnels and read their conversion statistics
- Log change markers and read the measured impact of a change
- Manage webhook endpoints and review their recent deliveries

## Use cases

### On-Site Behavior Evidence Review

Review what visitors actually did on a site using recordings and plain-language narratives rather than raw event logs. The API lists visits for a site and returns a narrative of a specific visit or page view. Product teams use this to understand friction on a page from observed behavior, not guesswork.

Example prompt: GET `/v1/projects/{projectId}/sessions` to list visits, then GET `/v1/projects/{projectId}/sessions/{sessionId}/narrative` to read what happened in one visit.

### Goal and Funnel Conversion Tracking

Measure how visitors convert by defining goals and funnels and reading their statistics, instead of stitching events together manually. The API creates a goal or funnel for a site and returns its conversion statistics. Growth teams use this to monitor conversion on key flows.

Example prompt: POST `/v1/projects/{projectId}/goals` to define a goal, then GET `/v1/projects/{projectId}/goals/stats` to read its conversion statistics.

### Change Impact Measurement

Tie a product change to its effect by logging a change marker and reading the impact Hoot Lens measures against it. The API records a change on a site and returns the measured impact of that change. Teams use this to confirm whether a release helped or hurt key behavior.

Example prompt: POST `/v1/projects/{projectId}/changes` to log a release, then GET `/v1/projects/{projectId}/changes/{changeId}/impact` to read its measured effect.

### Agent-Driven Analytics Readout

An AI agent produces a weekly on-site readout without a custom analytics client. Through Jentic the agent discovers the traffic and trend operations, loads their schemas, and calls them for a site, then summarizes what changed. This lets a reporting assistant answer behavior questions directly from the evidence.

Example prompt: Search Jentic for 'read site analytics', call GET `/v1/projects/{projectId}/traffic` and GET `/v1/projects/{projectId}/trends`, and summarise the week's traffic and trend changes.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/projects` | List tracked sites |
| GET | `/v1/projects/{projectId}/recordings` | List session recordings for a site |
| GET | `/v1/projects/{projectId}/sessions` | List visits for a site |
| GET | `/v1/projects/{projectId}/heatmaps` | List heatmap cohorts for a site |
| GET | `/v1/projects/{projectId}/goals` | List goals for a site |
| POST | `/v1/projects/{projectId}/goals` | Create a goal for a site |
| GET | `/v1/projects/{projectId}/funnels` | List funnels for a site |
| POST | `/v1/projects/{projectId}/changes` | Log a change marker |

## Key resources

- **Projects** — List, create, and update the sites you track and read install status
- **Recordings and Sessions** — Read session recordings, visits, and their plain-language narratives
- **Heatmaps and Traffic** — Read heatmap cohorts, sampled clicks, traffic, and weekly trends
- **Goals and Funnels** — Create goals and funnels and read their conversion statistics
- **Changes and Webhooks** — Log change markers, read their impact, and manage webhook endpoints

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 78 / 100
  - Developer Experience & Jentic Compatibility: 62 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 93 / 100
  - Security: 60 / 100
  - AI Discoverability: 69 / 100
- **View full report:** https://jentic.com/apis/hootlens.com/hootlens/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Hoot Lens by hand means handling its bearer auth, whether a Firebase token or a personal access token, and paging a site's evidence yourself. Through Jentic you install once, import Hoot Lens from the API Directory, store the credential once, and your agent calls the read endpoints.
- **Permission scoping:** Hoot Lens puts the site id in the URL path (`/v1/projects/{projectId}/...`), so a rule can pin your agent to one site. You choose the operations it may call, so write operations like deleting a goal or rotating a webhook secret are not included unless you add them.
- **Credential handling:** Your Hoot Lens token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'read site analytics' or 'list session recordings', and Jentic returns the matching Hoot Lens operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **PostHog API** — Product analytics with session replay and funnels
- **Heap API** — Autocapture product analytics and funnels
- **Plausible Analytics API** — Lightweight privacy-friendly traffic analytics

## FAQ

### Is there a Hoot Lens MCP server?

You do not need an MCP server to give your agent the Hoot Lens API. Jentic connects it directly from the API Directory: import Hoot Lens, store your token once, and your agent calls the recording, heatmap, and funnel endpoints. Operations are discovered on demand, so no extra server's tool definitions load into the agent's context.

### What authentication does the Hoot Lens API use?

The Hoot Lens API authenticates with a bearer token in the Authorization header, per its OpenAPI spec, and that credential is either a Firebase ID token for a signed-in person or a personal access token. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at call time, so it never enters the agent's prompt or logs.

### Can I read session recordings and heatmaps with the Hoot Lens API?

Yes. GET `/v1/projects/{projectId}/recordings` lists recordings, GET `/v1/projects/{projectId}/sessions/{sessionId}/narrative` returns a plain-language narrative of a visit, and GET `/v1/projects/{projectId}/heatmaps` lists heatmap cohorts with sampled clicks. Everything returned is observed behavior with its evidence.

### What are the rate limits for the Hoot Lens API?

The OpenAPI spec does not specify numeric rate limits for the Hoot Lens API. Check the Hoot Lens documentation at https://hootlens.com for the current limits that apply to your account.

### How do I read site analytics through Jentic?

Search Jentic with the query 'read site analytics', load the schema for GET `/v1/projects/{projectId}/traffic`, and execute it for your site, then read GET `/v1/projects/{projectId}/trends.` To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Hoot Lens API?

Yes. Write a rule that allows only the read operations under one project id, such as GET `/v1/projects/{projectId}/sessions` and GET `/v1/projects/{projectId}/heatmaps`, so the agent can read evidence for that one site and cannot change its goals, funnels, or webhooks, and every call it makes is logged.