Skip to main content

Metrics

Admin stats​

GET /api/v1/stats?company_id=

Auth: staff or company owner.

Counts: sent, delivered, bounced, complained, expired, failed, queued, suppressed, cancelled.

Grouped by by_lane, by_event (catalog event_type), and by_day. Query from, to, lane, and event_type narrow the window. The default window is 30 days.

sent includes every status the provider accepted. A later delivered or bounced row still counts as sent.

skipped counts accepted events that queued no message: no_recipients, no_rule, and rule_disabled (always 0).

Prometheus​

GET /api/v1/metrics

Auth: identity JWT, same scope as storage-service metrics (not public). Optional company_id.

The body is Prometheus text (text/plain; version=0.0.4). Accept: text/plain is accepted, including when it is listed with application/json. A missing Accept header is also accepted. 401 and 403 still return the JSON error_code body.

Gauges, computed from the database at scrape time:

NameLabelsMeaning
shellui_email_queue_depthlanequeued and retrying messages
shellui_email_queue_oldest_age_secondslaneAge of the oldest queued message
shellui_email_send_latency_secondslane, quantile (0.5, 0.95)Accept-to-handoff over the last 24 hours
shellui_email_provider_errorsprovider, error_codeErrors recorded in the last 24 hours
shellui_email_auth_ttl_expiriesnoneAuth messages that expired before handoff

Empty lanes are reported as 0 for depth and age so a scrape still lists auth, transactional, and bulk.

This endpoint never includes scheduled job or lane worker metrics.

Global Prometheus​

GET /api/v1/metrics/all

Auth: staff, or a personal access token with access_global_metrics (JWT claim pat_agm). Company owners get 403. A call without a token gets 401.

The body is the same queue gauges as GET /api/v1/metrics with no company_id, plus shellui_email_scheduled_job_*, shellui_email_scheduler_*, and shellui_email_lane_worker_*. Names, labels, and alert rules are in Scheduled jobs.