Analytics API

Use the analytics endpoint when you need a precomputed window comparison for a single event definition.

Endpoint:


GET /v1.0/events/:eventID/analytics

Required query parameters:

view=window
period=1h|1d|7d|1m
previous=previous_window|previous_1d|previous_7d|previous_1m

Supported window combinations

Period	Previous	What it compares
`1h`	`previous_window`	This hour vs the previous hour
`1h`	`previous_1d`	This hour vs the same hour yesterday
`1h`	`previous_7d`	This hour vs the same hour 7 days ago
`1h`	`previous_1m`	This hour vs the same hour 30 days ago
`1d`	`previous_window`	Today vs yesterday
`1d`	`previous_7d`	Today vs the same day last week
`1d`	`previous_1m`	Today vs the same day last month
`7d`	`previous_window`	This week vs last week
`7d`	`previous_1m`	This week vs the same week last month
`1m`	`previous_window`	This month vs last month

If a combination is not supported, the API returns 400.

Example request

Raw API


curl -G https://api.chirpier.co/v1.0/events/$EVENT_ID/analytics \
  -H "Authorization: Bearer $CHIRPIER_API_KEY" \
  --data-urlencode "view=window" \
  --data-urlencode "period=1h" \
  --data-urlencode "previous=previous_7d"

JavaScript


const analytics = await client.getEventAnalytics(EVENT_ID, {
  view: "window",
  period: "1h",
  previous: "previous_7d",
});

Python


analytics = client.get_event_analytics(
    EVENT_ID,
    view="window",
    period="1h",
    previous="previous_7d",
)

Go


analytics, err := client.GetEventAnalytics(ctx, EVENT_ID, chirpier.AnalyticsWindowQuery{
    View:     "window",
    Period:   "1h",
    Previous: "previous_7d",
})

Example response


{
  "event_id": "f6d2cf72-9f46-4f19-84fb-ff8f8e97d095",
  "view": "window",
  "period": "1h",
  "previous": "previous_7d",
  "data": {
    "current_value": 1280,
    "current_count": 64,
    "previous_value": 910,
    "previous_count": 52,
    "value_delta": 370,
    "count_delta": 12,
    "value_pct_change": 40.65934065934066,
    "count_pct_change": 23.076923076923077,
    "current_mean": 20,
    "previous_mean": 17.5,
    "mean_pct_change": 14.285714285714285,
    "mean_delta": 2.5,
    "current_stddev": 6.1,
    "previous_stddev": 5.4
  }
}

Response fields

Field	Description
`current_value`	Sum of all values in the current window
`current_count`	Number of logs in the current window
`current_mean`	Average value per log (`current_value / current_count`)
`current_stddev`	Estimated standard deviation from aggregated squares
`previous_value`	Sum of all values in the comparison window
`previous_count`	Number of logs in the comparison window
`previous_mean`	Average value per log in the comparison window
`previous_stddev`	Standard deviation in the comparison window
`value_delta`	`current_value - previous_value`
`count_delta`	`current_count - previous_count`
`mean_delta`	`current_mean - previous_mean`
`value_pct_change`	Percentage change in value relative to the previous window
`count_pct_change`	Percentage change in count relative to the previous window
`mean_pct_change`	Percentage change in mean relative to the previous window

The response field names do not change by comparison type. For example, period=1h&previous=previous_7d still returns previous_value, not last_week_value.

Reading the response

Using the example response above (period=1h, previous=previous_7d):

Total value this hour: 1280 (sum of all logged values)
Total value same hour last week: 910
Value is up 40.7% from the same hour 7 days ago (value_pct_change)
Average per log: 20 now vs 17.5 last week, a 14.3% increase (mean_pct_change)
Volume: 64 logs now vs 52 last week, 23% more activity (count_pct_change)
Spread: standard deviation widened slightly (6.1 vs 5.4), meaning values are a bit more variable

If data is null, there were no logs in either window.

Notes

use previous, not compare
analytics windows are separate from rollup periods like minute, hour, and day
day and larger windows respect the event definition timezone
public event sharing uses event_id together with share_token, but analytics reads still use the authenticated control-plane API

Use API Reference for the broader control-plane contract, Event Taxonomy for generic naming guidance, chirpier-skills for the agent workflow layer, and Canonical Event Names for the OpenClaw-specific path.