# Agent Analytics

> Web analytics platform with an agent-friendly HTTP API. Track events across multiple projects, then let your agent read the stats.

## What is Agent Analytics?

Agent Analytics is a web analytics platform designed for developers who ship many projects (using AI tools like Cursor, Bolt, Claude Code) and want their AI agent to monitor all of them. Instead of logging into separate dashboards for each project, your agent queries a single REST API and reports back.

- Open source under MIT license
- Privacy-friendly: no cookies, no IP addresses, no personal data
- Lightweight tracker: ~2KB script tag
- API-first: structured JSON responses your agent can act on
- Multi-project account model: one account, one API key, 2 projects on hosted free, unlimited on paid or self-hosted

## How It Works

1. **Sign up** at https://app.agentanalytics.sh — create a project, get a project token and API key
2. **Add tracking** to your site with one script tag:
   ```html
   <script src="https://api.agentanalytics.sh/tracker.js"
           data-project="my-project"
           data-token="aat_your_token_here"></script>
   ```
3. **Query stats** via API using your API key:
   ```
   GET https://api.agentanalytics.sh/stats?project=my-project&days=7
   Header: X-API-Key: aak_your_key_here
   ```
4. **Automate**: Have your AI agent check stats daily and report back to you.

## Authentication

Two types of credentials:

- **Project Token** (`aat_*`): Public, embedded in your site's HTML. Used for event ingestion (`POST /track`). Passed in the request body — no custom headers, no CORS preflight needed.
- **API Key** (`aak_*`): Secret, used for reading data. Passed via `X-API-Key` header or `?key=` query parameter.

## API Endpoints

Base URL: `https://api.agentanalytics.sh`

### Ingestion (project token required)

**POST /track** — Track a single event
```json
{
  "project": "my-project",
  "token": "aat_your_token",
  "event": "page_view",
  "properties": {
    "path": "/pricing",
    "referrer": "https://google.com"
  }
}
```
Response: `202 Accepted`

**POST /track/batch** — Track up to 100 events at once
```json
{
  "project": "my-project",
  "token": "aat_your_token",
  "events": [
    { "event": "page_view", "properties": { "path": "/" } },
    { "event": "cta_click", "properties": { "id": "signup" } }
  ]
}
```

### Query (API key required)

All query endpoints require `X-API-Key: aak_your_key` header.

**GET /stats** — Aggregated overview
```
GET /stats?project=my-project&days=7
```
Returns: total events, unique visitors, top pages, top referrers, browser/OS/device breakdowns.

**GET /events** — Raw event log
```
GET /events?project=my-project&event=page_view&days=7&limit=100
```
Returns: array of individual event records with timestamps and properties.

**POST /query** — Flexible analytics query
```json
{
  "project": "my-project",
  "metrics": ["count", "unique_visitors"],
  "group_by": ["properties.path"],
  "filters": [
    { "field": "event", "op": "eq", "value": "page_view" }
  ],
  "order_by": { "field": "count", "direction": "desc" },
  "days": 30,
  "limit": 10
}
```

**GET /properties** — Discover event names and property keys
```
GET /properties?project=my-project&days=30
```
Returns: list of event names and their associated property keys. Useful for building dynamic queries.

**GET /health** — Health check
```
GET /health
```
Returns: `{ "status": "ok" }`

## Tracker Script

The tracker collects: page URL, path, hostname, page title, referrer, screen resolution, browser name and version, OS, device type (desktop/mobile/tablet), language, and UTM parameters. A random anonymous ID is stored in localStorage and a session ID in sessionStorage (30-min inactivity timeout).

No cookies. No IP addresses. No personal data.

Auto-tracks `page_view` events. You can also track custom events:
```javascript
window.aa.track('cta_click', { id: 'signup_button' });
```

## Self-Hosting

Agent Analytics can be self-hosted. Two deployment options:

### Cloudflare Workers + D1 (recommended)
- Free tier handles 100K events/day
- Global edge deployment
- Zero maintenance
- Repository: https://github.com/Agent-Analytics/agent-analytics

### Node.js + SQLite
- Run anywhere: VPS, Docker, Raspberry Pi
- Same codebase, same API
```bash
API_KEYS=my-secret-key PROJECT_TOKENS=pt_my-token npm start
```

## Pricing

### Self-Hosted (Open Source)
- Free forever
- MIT licensed
- No limits
- Your data stays on your infrastructure

### Hosted — Free Tier
- $0
- 2 projects
- 100,000 events per month
- 500 agent/API reads per month
- 90-day data retention
- Core analytics surface only + limited MCP
- 1 API key

### Hosted — Pay as you go
- $1 per 10,000 events
- Billing starts at event 1 after upgrade
- Unlimited projects
- Unlimited events
- 12-month data retention
- Unlimited API keys
- Full API, CLI, and MCP surface
- No contracts, cancel anytime

Sign up: https://app.agentanalytics.sh

## Integrations

Works with any AI agent that can make HTTP requests:
- OpenClaw (AI agent platform)
- Claude Code (Anthropic CLI)
- Cursor / Bolt (AI code editors)
- Any custom agent or script

## Data Privacy

- No cookies
- No IP address collection
- No personal data
- Data stored in isolated Cloudflare D1 database per project
- Not sold, shared, or used for advertising
- GDPR-friendly by design

## Links

- Website: https://agentanalytics.sh
- Dashboard: https://app.agentanalytics.sh
- API Base: https://api.agentanalytics.sh
- GitHub: https://github.com/Agent-Analytics/agent-analytics
- Privacy Policy: https://agentanalytics.sh/privacy
- Terms of Service: https://agentanalytics.sh/terms
- DPA: https://agentanalytics.sh/dpa
- Contact: contact@agentanalytics.sh
- Support: support@agentanalytics.sh
- X: https://x.com/analytics_90590