Analytics Queries API

Query analytics metrics and events from PULSE

Analytics Queries API

Query aggregated metrics and analytics data from PULSE.

Endpoint

GET /api/v1/stats

Authentication

Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Required	Description
`site_id`	string	✓	Site identifier
`metric`	string	✓	Metric name
`start_date`	number		Start timestamp (ms)
`end_date`	number		End timestamp (ms)
`period`	string		Time period: 1h, 24h, 7d, 30d
`group_by`	string		Group by: hour, day, device_type, country
`country`	string		Filter by country code
`device_type`	string		Filter by device type

Metrics

Basic Metrics:

Metric	Description
`event_count`	Total number of events
`unique_users`	Count of unique users
`unique_sessions`	Count of unique sessions
`avg_session_duration`	Average session length in seconds

Custom Metrics:

Metric	Description
`event_count_by_type`	Events grouped by type
`bounce_rate`	Percentage of single-event sessions
`conversion_rate`	Percentage of sessions with target event

Response

{
  "success": true,
  "data": {
    "metric": "event_count",
    "value": 1234,
    "period": "24h",
    "site_id": "site_abc123",
    "breakdown": [
      {
        "timestamp": 1703001234567,
        "value": 142
      }
    ]
  },
  "timestamp": 1703001234567
}

Examples

Basic Query

curl "https://api.example.com/api/v1/stats?site_id=site_abc123&metric=event_count" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "metric": "event_count",
    "value": 1234,
    "timestamp": 1703001234567
  }
}

Time Series Query

curl "https://api.example.com/api/v1/stats?site_id=site_abc123&metric=event_count&group_by=hour&period=24h" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filtered Query

curl "https://api.example.com/api/v1/stats?site_id=site_abc123&metric=event_count&country=US&device_type=mobile" \
  -H "Authorization: Bearer YOUR_API_KEY"

Status Codes

Code	Meaning
200	Success
400	Bad request (invalid parameters)
401	Unauthorized
404	Site not found

Next Steps

Event Ingestion — Send events
Cohort Analysis — Cohort queries

Last updated: April 3, 2026