Beam Stats API

Authentication

Generate or revoke your key at /dashboard/billing. Keys are shown only once when generated.

Authorization: Bearer beam_your_api_key_here

Rate limit: 60 requests/minute per API key. Free accounts receive HTTP 403 with upgrade guidance.

GET /api/v1/sites

Returns all sites owned by the authenticated user.

curl -s https://beam.keylightdigital.dev/api/v1/sites \
  -H "Authorization: Bearer beam_your_api_key_here"

{
  "sites": [
    { "id": "site_123", "domain": "example.com", "name": "Example" }
  ]
}

GET /api/v1/sites/:id/stats?range=7d|30d|today

Returns summary metrics and top traffic breakdowns for a site in the selected UTC range.

curl -s "https://beam.keylightdigital.dev/api/v1/sites/site_123/stats?range=7d" \
  -H "Authorization: Bearer beam_your_api_key_here"

{
  "range": "7d",
  "pageviews": 842,
  "uniqueVisitors": 311,
  "topPages": [{ "path": "/", "visitors": 220, "pageviews": 415 }],
  "topReferrers": [{ "source": "google.com", "visitors": 137 }],
  "topCountries": [{ "country": "US", "visitors": 182 }],
  "channels": {
    "Search": { "visitors": 137, "pageviews": 241 },
    "Direct": { "visitors": 98, "pageviews": 190 }
  }
}

GET /api/v1/sites/:id/events?range=7d|30d|today

Returns custom event counts with property breakdowns.

curl -s "https://beam.keylightdigital.dev/api/v1/sites/site_123/events?range=7d" \
  -H "Authorization: Bearer beam_your_api_key_here"

{
  "range": "7d",
  "events": [
    {
      "name": "signup_click",
      "count": 24,
      "properties": {
        "plan": { "pro": 11, "free": 13 },
        "source": { "pricing": 20 }
      }
    }
  ]
}