API Reference

The Analytics Platform API v2 lets you programmatically access your analytics data. Use it to build dashboards, automate reporting, or integrate analytics into your workflow.

Base URL

https://your-domain.com/api/v2

Authentication

All API requests require an API key. Generate one from Dashboard → Settings → API Keys.

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-domain.com/api/v2/sites

Rate Limits

API requests are limited to 100 requests per minute per API key.

Rate limit headers in response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1711612800000

When rate-limited, you'll receive a 429 status with a Retry-After header.

List Sites

GET/api/v2/sites

Returns all sites the authenticated user has access to.

Response Example

{
  "sites": [
    {
      "siteId": "6507f1f77bcf86cd799439011",
      "name": "My Website",
      "domain": "example.com",
      "isActive": true,
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Site Analytics

GET/api/v2/sites/:siteId/stats

Get aggregated analytics for a site within a date range.

Query Parameters

Name	Type	Required	Description
range	string	No	Date range: 7d, 30d, or 90d (default: 7d)

Response Example

{
  "visitors": 1234,
  "pageviews": 5678,
  "bounceRate": 42,
  "avgDuration": 145,
  "topPages": [
    { "pathname": "/", "views": 2000 },
    { "pathname": "/pricing", "views": 800 }
  ],
  "topReferrers": [
    { "referrer": "google.com", "count": 500 }
  ],
  "browsers": [
    { "browser": "Chrome", "count": 3000 }
  ],
  "countries": [
    { "country": "US", "count": 2000 }
  ]
}

Real-time Data

GET/api/v2/sites/:siteId/realtime

Get currently active visitors and pages (last 5 minutes).

Response Example

{
  "activeVisitors": 42,
  "activePages": [
    { "path": "/", "visitors": 15 },
    { "path": "/pricing", "visitors": 8 }
  ]
}

Event List

GET/api/v2/sites/:siteId/events

Get custom events tracked on a site, grouped by name with counts.

Query Parameters

Name	Type	Required	Description
range	string	No	Date range: 7d, 30d, or 90d (default: 7d)

Response Example

{
  "events": [
    { "name": "signup_click", "count": 234 },
    { "name": "download_pdf", "count": 89 }
  ]
}

Pageview Detail

GET/api/v2/sites/:siteId/pageviews

Get pageview totals and a daily chart, optionally filtered by pathname.

Query Parameters

Name	Type	Required	Description
range	string	No	Date range: 7d, 30d, or 90d (default: 7d)
pathname	string	No	Filter by specific page path (e.g. /pricing)

Response Example

{
  "total": 5678,
  "unique": 1234,
  "chart": [
    { "date": "2025-03-21", "count": 800 },
    { "date": "2025-03-22", "count": 920 }
  ]
}

Error Codes

All errors return a JSON object with an error field.

Status	Description
401	Unauthorized — missing or invalid API key
403	Forbidden — you do not have access to this resource
429	Rate limit exceeded — wait and retry
500	Internal server error

{
  "error": "Unauthorized — provide a valid API key"
}