API key or dashboard session

Statistics

Fetch dashboard statistics for all time or a selected reporting scope.

GET
/v1/stats
API key scope stats:read or user session - Fetch user statistics with an optional scope query parameter.
GET
/v1/stats/:scope
API key scope stats:read or user session - Fetch user statistics for a scope supplied in the path.

Overview

The Statistics API returns dashboard metrics and chart series for the authenticated user. Use an API key with stats:read or an authenticated dashboard session.

The default scope is 1month. Supported scopes are 24h, 1w, 1month, 1year, and all. The all scope covers the authenticated account's creation time through today and automatically selects hourly, daily, weekly, or 30-day chart buckets for the account's age. Backend reporting windows and chart buckets use GMT+1. Browser UI code formats dates in the user's local timezone.

GET /v1/stats

curl "https://api.bar9.dev/v1/stats?scope=1w" \
  -H "Authorization: Bearer $BAR9_API_KEY"

If scope is omitted, the endpoint uses 1month.

GET /v1/stats/:scope

Pass the reporting scope in the path instead of the query string:

curl https://api.bar9.dev/v1/stats/all \
  -H "Authorization: Bearer $BAR9_API_KEY"

Query parameters

Field Required Notes
scope No One of 24h, 1w, 1month, 1year, or all. Defaults to 1month.

If both forms are present, use one endpoint style consistently rather than relying on precedence.

Response

{
	"ok": true,
	"data": {
		"total_messages": 1280,
		"sent_today": 14,
		"sent_this_month": 310,
		"messages_today": 14,
		"messages_month_to_date": 310,
		"messages_previous_month": 245,
		"scoped_messages": 143,
		"scoped_increase_percent": 12.5,
		"success_rate_percent": 96.8,
		"otp_verification_success_rate_percent": 82.3,
		"credit_balance": 4200,
		"charts": {
			"scope": "1w",
			"labels": ["Jun 04", "Jun 05"],
			"messages": [{ "bucket": 1780527600, "label": "Jun 04", "total": 41 }],
			"otps": [{ "bucket": 1780527600, "label": "Jun 04", "total": 12 }],
			"campaigns": [{ "bucket": 1780527600, "label": "Jun 04", "total": 4 }],
			"operators": [
				{ "operator": "ooredoo", "total": 63 },
				{ "operator": "mobilis", "total": 51 },
				{ "operator": "djeezy", "total": 29 }
			]
		},
		"recent_activity": []
	}
}

Response fields

Field Notes
total_messages All-time count for the authenticated user.
sent_today Backward-compatible alias for messages_today.
sent_this_month Backward-compatible alias for messages_month_to_date.
messages_today Messages created today in the GMT+1 backend reporting day.
messages_month_to_date Messages created this month in GMT+1.
messages_previous_month Messages created in the previous GMT+1 calendar month.
scoped_messages Message count inside the selected scope.
scoped_increase_percent Percentage change against the previous matching scope. Values are not capped at 100%; all returns 0.
success_rate_percent Percentage of scoped messages with sent or delivered status.
otp_verification_success_rate_percent Percentage of scoped OTP sessions that were verified.
charts.* Chart labels, series, and operator totals for the selected scope.

Common errors

Status Typical cause
400 Unsupported scope.
401 Missing or invalid API key or dashboard session.
403 API key does not include the stats:read scope.