# Agent Analytics

> Installation guides plus API reference for the analytics platform AI agents can query.

API base URL: https://api.agentanalytics.sh

## Docs

- [Docs Home](https://docs.agentanalytics.sh): Guide-first docs homepage
- [API Reference](https://docs.agentanalytics.sh/api/): Interactive Scalar API reference
- [OpenAPI Spec](https://docs.agentanalytics.sh/openapi.yaml): Machine-readable OpenAPI 3.1 spec
- [Full Docs + API Reference](https://docs.agentanalytics.sh/llms-full.txt): LLM-friendly complete export

### Guides
- [Guides](https://docs.agentanalytics.sh/guides/): Task-oriented guides for setting up Agent Analytics and running experiments through AI agents such as Claude Code, Cursor, Codex, and OpenClaw.
- [Getting Started](https://docs.agentanalytics.sh/getting-started/): Create a project, install Agent Analytics in your AI agent, and verify the first query.
- [Set up Agent Analytics for your Paperclip company](https://docs.agentanalytics.sh/guides/paperclip/): Ask the user to create one CEO task, then review the blocked task when login approval is needed, and finally query the live project.
- [Agent Analytics Skill](https://docs.agentanalytics.sh/guides/agent-analytics-skill/): Install the regular Agent Analytics skill and let your coding agent create projects, add tracking, query analytics, and run experiments from the same workflow.
- [Autoresearch Growth Skill](https://docs.agentanalytics.sh/guides/autoresearch-growth-skill/): Use the Agent Analytics Autoresearch skill to run a loop on top of the loop: generate variants, judge them, ship approved experiments, measure real behavior, and feed the next run.
- [First Project in 5 Minutes](https://docs.agentanalytics.sh/guides/first-project-in-5-minutes/): Go from installed agent to a live Agent Analytics project with the tracker placed, the first page view verified, and one real analytics question answered.
- [AI Agent Experiment Tracking](https://docs.agentanalytics.sh/guides/ai-agent-experiment-tracking/): Run website and app A/B tests through your AI agent with prompt-first experiment setup, declarative variants, QA, and results review.
- [Session Paths](https://docs.agentanalytics.sh/guides/session-paths/): Use bounded session paths to help your AI agent connect entry pages, exit pages, goals, funnels, retention, and experiments without opening a dashboard.

### Installation
- [Installation Overview](https://docs.agentanalytics.sh/installation/): Choose the native Agent Analytics access path for Claude, Cursor, OpenClaw, Codex, and related AI tools.
- [Claude Code](https://docs.agentanalytics.sh/installation/claude-code/): Install Agent Analytics in Claude Code with the hosted plugin first, then use the skill path before dropping to raw MCP setup.
- [Web Analytics MCP for Claude Desktop / Cowork](https://docs.agentanalytics.sh/installation/claude-desktop-cowork/): Connect the Agent Analytics web analytics MCP server in Claude Desktop or Cowork and query analytics directly in chat.
- [Cursor](https://docs.agentanalytics.sh/installation/cursor/): Install the Agent Analytics skill in Cursor and use CLI-style workflows first. Use MCP only when you specifically want connector-style tool calls.
- [OpenClaw](https://docs.agentanalytics.sh/installation/openclaw/): Install the Agent Analytics skill in OpenClaw from ClawHub, use browser approval plus finish-code handoff as the normal login path, and keep the workflow inside chat.
- [OpenAI Codex](https://docs.agentanalytics.sh/installation/openai-codex/): Install the Agent Analytics skill for OpenAI Codex, use browser approval when login is needed, and keep project setup in the same agent flow.

### Reference
- [Tracker.js](https://docs.agentanalytics.sh/reference/tracker-js/): Add Agent Analytics to any site with one script tag, then turn on declarative events, consent, performance tracking, and other browser-side features.
- [Bot Traffic](https://docs.agentanalytics.sh/reference/bot-traffic/): See which automated callers hit your tracker, how many events were filtered, and which actors generated that traffic.
- [Authentication](https://docs.agentanalytics.sh/reference/authentication/): Understand the difference between agent sessions, API keys, and project tokens before you wire an agent or a tracker.
- [Plugin vs Skill vs MCP vs API](https://docs.agentanalytics.sh/reference/cli-mcp-api/): Agent Analytics exposes one analytics surface through plugin, skill, MCP, CLI, and raw HTTP. Use this page to choose the native path that fits the environment your AI agent already uses.
- [Rate Limits](https://docs.agentanalytics.sh/reference/rate-limits/): Hosted Agent Analytics uses account-level API limits and event-volume limits that vary by plan.
- [Error Format](https://docs.agentanalytics.sh/reference/error-format/): All API errors return a machine-readable code plus a human-readable message.

## MCP Server

URL: https://mcp.agentanalytics.sh/mcp (Streamable HTTP transport)

Add to Claude Code:
```
claude mcp add agent-analytics --transport http https://mcp.agentanalytics.sh/mcp
```

Tools: `list_projects`, `create_project`, `all_sites_overview`, `analytics_overview`, `bot_traffic_overview`, `all_sites_bot_traffic`, `analytics_insights`, `analytics_breakdown`, `analytics_pages`, `analytics_paths`, `analytics_sessions`, `analytics_heatmap`, `analytics_funnel`, `analytics_retention`, `properties`, `properties_received`, `sessions`, `list_experiments`, `create_experiment`, `get_experiment`, `update_experiment`, `delete_experiment`, `live_now`, `query`

Hosted free accounts can use MCP for `list_projects`, `create_project`, `all_sites_overview`, `analytics_overview`, `bot_traffic_overview`, and `all_sites_bot_traffic`. The rest of the MCP tool surface requires a paid account.

## Agent Skill

Install as an agent skill (works with Claude Code, Codex, and other Agent Skills-compatible tools):
```
npx skills add Agent-Analytics/agent-analytics-skill
```

## Quick Start

1. Pick an install path from https://docs.agentanalytics.sh/installation/
2. Ask your AI agent to set up Agent Analytics, open the browser for you or send you a login link, and wait
3. Sign in with Google or GitHub, approve it, and paste back any finish code if the agent asks
4. Let the agent create the project and either add the tracker or return the snippet for you to paste
   - If using Astro, add `is:inline` to the tracker `<script>` tag.
5. Query stats by asking your agent something like `How is my-site doing this week?`

## Authentication

- **Agent Session** (`aas_*`): Browser-approved session used by the official CLI and agent-first onboarding flows.
- **API Key** (`aak_*`): Secret key for direct API access and advanced/manual runtimes. Pass via `X-API-Key` header or `?key=` query param.
- **Project Token** (`aat_*`): Public token for event ingestion. Passed in request body.

## Endpoints

### Ingestion
- `POST /track` — Track a single event
- `POST /track/batch` — Track multiple events
- `POST /identify` — Link anonymous user to authenticated identity

### Analytics
- `GET /stats` — Aggregated stats overview
- `GET /events` — Raw event log
- `POST /query` — Flexible analytics query
- `GET /properties` — Discover event names and property keys
- `GET /properties/received` — Property keys by event name
- `GET /sessions` — List sessions
- `GET /breakdown` — Top property values
- `GET /insights` — Period-over-period comparison
- `GET /pages` — Entry/exit page stats
- `GET /sessions/distribution` — Session duration histogram
- `GET /heatmap` — Day-of-week x hour traffic grid
- `GET /retention` — Cohort retention analysis
- `GET /bot-traffic` — Filtered automated traffic for one project

### Projects
- `GET /projects` — List all projects
- `POST /projects` — Create a new project
- `GET /projects/{id}` — Get project details
- `PATCH /projects/{id}` — Update a project
- `DELETE /projects/{id}` — Delete a project

### Website Analysis
- `POST /website-scans` — Analyze product growth measurement blind spots
- `GET /website-scans/{id}` — Resume a website analysis
- `POST /website-scans/{id}/upgrade` — Claim and upgrade an analysis

### Account
- `GET /account` — Get account info
- `GET /account/all-sites` — Historical all-sites overview
- `GET /account/bot-traffic` — Filtered automated traffic across all active projects
- `POST /account/revoke-key` — Revoke and regenerate API key
- `POST /account/feedback` — Submit product or workflow feedback

### Agent Sessions
- `POST /agent-sessions/start` — Start an agent-session signup/login flow
- `GET /agent-sessions/authorize/{id}` — Browser approval page for an auth request
- `POST /agent-sessions/poll` — Poll detached auth status
- `POST /agent-sessions/exchange` — Exchange an approved auth request for an agent session
- `POST /agent-sessions/refresh` — Refresh an agent session access token
- `POST /agent-sessions/revoke` — Revoke an agent session
- `GET /account/agent-sessions` — List active and historical agent sessions for the account

### Experiments
- `GET /experiments/config` — Get experiment config for tracker.js
- `POST /experiments` — Create an A/B experiment
- `GET /experiments` — List experiments
- `GET /experiments/{id}` — Get experiment with live results
- `PATCH /experiments/{id}` — Update experiment status
- `DELETE /experiments/{id}` — Delete an experiment

### Funnels
- `POST /funnel` — Funnel analysis

### Paths
- `POST /paths` — Bounded session path analysis

### Streaming
- `GET /stream` — Live event stream (SSE)
- `GET /live` — Live snapshot (real-time)

### Tracking
- `GET /tracker.js` — JavaScript tracker script

## Rate Limits

| Tier | Requests/min | Event Limit | Data Retention |
|------|-------------|-------------|----------------|
| Free | 10 | 100,000 / month | 90 days |
| Pro  | 1,000 | Unlimited | 365 days |

Hosted free also includes 2 projects and 500 agent/API read actions per month. Paid starts at $1 per 10,000 events and unlocks the full API, CLI, and MCP surface.