# Agent Analytics Docs > Guides, installation pages, reference pages, and the full API reference for Agent Analytics. ## Guides URL: https://docs.agentanalytics.sh/guides/ Task-oriented guides for setting up Agent Analytics and running experiments through your AI agent. Use these guides when you want to tell an AI agent what to do, not manually stitch together the low-level steps yourself. ## Start with the right guide If you need environment-specific setup, use the [installation hub](/installation/). If you need low-level browser or endpoint details, continue to [Tracker.js](/reference/tracker-js/) or the [API reference](/api/). ## Getting Started URL: https://docs.agentanalytics.sh/getting-started/ Create a project, install Agent Analytics in your agent, and verify the first query. This is the shortest path from zero to a working Agent Analytics setup. If your agent is already installed and you want the clearest create-project, place-snippet, and verify-first-page-view walkthrough, use [First Project in 5 Minutes](/guides/first-project-in-5-minutes/). ## 1. Get your API key Sign up at [app.agentanalytics.sh](https://app.agentanalytics.sh) and generate an API key from the dashboard. - Use the API key (`aak_*`) for reads, project management, and agent skill setup. - Use the project token (`aat_*`) in the tracking snippet that goes on your site. ## 2. Pick and complete an install path Go to the [installation hub](/installation/) and complete the setup for the environment you actually use: - [Claude Code](/installation/claude-code/) - [Claude Desktop / Cowork](/installation/claude-desktop-cowork/) - [Cursor](/installation/cursor/) - [OpenClaw](/installation/openclaw/) - [OpenAI Codex](/installation/openai-codex/) If none of those are a fit, the [API reference](/api/) stays available for direct integration. ## 3. Create your first project After your agent is connected, ask it to create the first project for you: - `Create a project called my-site.com` - `Create a project called my-site.com and give me the tracking snippet` If your agent has code write access to your site, ask it: - `Set up analytics for my-site.com` Your agent should create the project and either: - return the tracker snippet for you to paste, or - install the tracker itself if it can edit the site ## 4. Add the tracker manually if needed If your agent already added the tracker to your site, skip this step. If it only created the project and returned a snippet, add the script before ``: ```html ``` Page views are tracked automatically. Add custom events later with `data-aa-event` attributes or `window.aa.track()`. If your site uses Astro, add `is:inline` to that tracker tag. For advanced tracker options like declarative events, cross-domain identity, consent, scroll depth, vitals, and error tracking, use the [Tracker.js guide](/reference/tracker-js/). If your app is a SPA, use [SPA and Virtual Page Tracking](/guides/spa-and-virtual-page-tracking/) to understand what Agent Analytics auto-tracks and when to send a manual virtual `page_view`. If you want your agent to launch your first browser-side A/B test after setup, continue with [AI Agent Experiment Tracking](/guides/ai-agent-experiment-tracking/). ## 5. Verify the loop Once the install is working and the tracker is live, ask your agent one of these: - `List my projects` - `How is my-site doing this week?` - `What are the top pages for my-site this week?` - `Show bot traffic for my-site this week` If the setup is correct, the agent should answer without you hand-writing requests. ## Next - Use [Installation](/installation/) for the fastest per-agent setup. - Use [First Project in 5 Minutes](/guides/first-project-in-5-minutes/) when you want the full activation walkthrough from installed agent to first live project. - Use [SPA and Virtual Page Tracking](/guides/spa-and-virtual-page-tracking/) when your app changes screens client-side and you need accurate page tracking without double-counting. - Use [AI Agent Experiment Tracking](/guides/ai-agent-experiment-tracking/) when you want your agent to launch and read browser-side experiments for you. - Use [Tracker.js](/reference/tracker-js/) for browser-side tracking options. - Use [Bot Traffic](/reference/bot-traffic/) to inspect filtered automated callers separately from normal analytics. - Use [Authentication](/reference/authentication/) when you need the read token vs write token rules. - Use [API Reference](/api/) when you need endpoint-level details. ## First Project in 5 Minutes URL: 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. Use this guide when your agent install is already done and you want the clearest path to your first real success loop. If you still need to connect your agent first, go back to the [installation hub](/installation/) or the short [Getting Started](/getting-started/) overview. ## 1. Confirm your agent install is already working Ask your agent: ```text List my Agent Analytics projects and confirm you can reach my account. ``` If the agent cannot see your account yet, stop here and finish the right [installation path](/installation/). ## 2. Create the first project and get the tracker snippet Ask your agent: ```text Create a project called my-site.com and give me the tracking snippet. ``` At this point you want one of two outcomes: - the agent creates the project and returns the tracker snippet for you to paste - the agent creates the project and can place the snippet itself ## 3. Choose the path that matches your setup ### Agent can edit code If your agent can change your site, ask it: ```text Create a project called my-site.com, add the Agent Analytics tracking snippet to the site, and tell me exactly which file you changed. ``` Then ask: ```text Show me where you placed the snippet and confirm it will load on the page I want to track first. ``` If your site uses Astro, tell the agent to add `is:inline` to the tracker ` ``` Required attributes: - `data-project`: your project name - `data-token`: the public project token (`aat_*`) The tracker automatically collects page URL, pathname, referrer, browser, OS, device, language, timezone, UTM params, session count, and first-touch attribution. No cookies are required. Automated traffic that reaches the tracker is filtered out of your normal analytics. Use [Bot Traffic](/reference/bot-traffic/) if you want to inspect those automated requests separately. If your agent can edit code, ask it to add the snippet for you. If not, use [First Project in 5 Minutes](/guides/first-project-in-5-minutes/) to create the project, get the snippet, and verify the first page view. ## Common options | Attribute | What it does | | --- | --- | | `data-link-domains="example.com"` | Link anonymous identity across sibling domains or subdomains | | `data-do-not-track="true"` | Respect the browser Do Not Track signal | | `data-heartbeat="15"` | Measure active time on page while the tab is visible | | `data-track-outgoing="true"` | Track external link clicks as `outgoing_link` | | `data-track-clicks="true"` | Track `` and ` ``` That fires a `signup` event with `{ plan: "pro" }`. This is usually the easiest path for agents too. They can add attributes to existing markup instead of wiring `onclick` handlers or editing application code. ## Impressions Track whether a section was actually seen: ```html

``` When the element becomes visible, the tracker sends an `$impression` event. ## `window.aa` API Use the JavaScript API when the event depends on runtime state: ```js window.aa?.track('checkout_started', { plan: 'pro' }); window.aa?.identify('user_123'); window.aa?.set({ plan: 'pro', team: 'acme' }); ``` Useful methods: - `aa.track(event, properties)`: send a custom event - `aa.page(name)`: manually send a page view - `aa.identify(id)`: link anonymous behavior to a known user ID - `aa.set(properties)`: attach global properties to future events - `aa.experiment(name, variants)`: assign variants deterministically client-side - `aa.grantConsent()` / `aa.revokeConsent()`: manage consent mode ## SPA routing and virtual pages Agent Analytics automatically tracks `page_view` when the browser URL changes through `history.pushState()`, `history.replaceState()`, `popstate`, or `hashchange`. That covers most client-side routers, including hash-based SPAs. If your UI changes without changing the path, query string, or hash, the tracker does not try to guess that a new screen appeared. In that case, send a manual `page_view`. Preferred implementation order: 1. Real URL changes 2. Hash routing 3. Manual virtual `page_view` Use `aa.page(name)` when the current browser URL already matches the screen you want to label. It sends a `page_view` with a `page` property, but `path` and `url` still come from the current browser location. For true virtual pages with no URL change, send a manual `page_view` and override the route fields yourself: ```js window.aa?.track('page_view', { page: 'Checkout Step 2', path: '/checkout/step-2', url: `${location.origin}/checkout/step-2` }); ``` Do not combine manual page tracking with router-driven transitions that Agent Analytics already auto-tracks, or you will double-count the same screen change. If you want a prompt-first workflow for deciding between router tracking and manual virtual pages, use [SPA and Virtual Page Tracking](/guides/spa-and-virtual-page-tracking/). ## Common recipes ### Cross-domain identity ```html ``` ### Privacy and consent ```html ``` ```js window.aa?.grantConsent(); window.aa?.revokeConsent(); ``` ### Experiments ```html

Start your free trial