lumen.dashboard.summary

Fleet-level observability KPI snapshot (log counts, error counts, latency, tokens, cost)

Fleet-level observability KPI snapshot for an organization.

Returns log counts, error counts, open error groups, active alerts, p95 LLM latency, token usage, cost, and period-over-period deltas for the caller's organization and a rolling time window. Designed for agents and operators who need a high-level health snapshot before triaging incidents or generating reports.

Auth: direct Lumen API call using the LUMEN_API_KEY service key with X-Lumen-Organization-UUID forwarding. See module docstring for the known server-side limitation around cross-org data isolation on the platform-bypass path.

NOTE on active_alerts: the field counts open critical error groups, not fired alert rule events. Its semantics will change once Lumen ships the alert_rule_events table.

NOTE on p95_latency_ms: reflects llm.latency_ms gauge metrics only, not general HTTP or span latency. Do not use as a general API latency signal.

NOTE on cost_24h: always zero until agents.session.total_cost_usd metric emission is instrumented.

Overview

Property	Value
Workflow type	Atomic
Library	App-lumen
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	UUID of the organization for which the summary is requested
project	string	No	—	Project filter (wildcards supported: , prefix-, -suffix). Default on the Lumen side is '' (all projects).
window	string	No	—	Rolling time window: one of 1h, 6h, 24h, 7d. Default: 24h.

Output Schema

Field	Type	Required	Default	Description
window	string	No	—	Echoes the applied window in hours format (e.g. '24h', '168h' for '7d'). Lumen always returns f'{window_hours}h' regardless of the input string.
from	string	No	—	ISO 8601 UTC datetime of the rolling window lower bound (server-computed)
to	string	No	—	ISO 8601 UTC datetime of the rolling window upper bound (server-computed)
workflows	integer	No	—	Count of distinct workflow_state_id values in the requested window.
errors	integer	No	—	Count of ERROR + CRITICAL log entries in the requested window.
tokens	integer	No	—	Total llm.tokens.input + llm.tokens.output metric sum in the requested window.
cost	float	No	—	Total agents.session.total_cost_usd metric sum in the requested window.
workflows_24h	integer	No	—	Count of distinct workflow_state_id values from log_entries in the window. Label is fixed as _24h regardless of the actual window parameter.
errors_24h	integer	No	—	Count of ERROR + CRITICAL log entries in the window
open_error_groups	integer	No	—	Count of all open error_groups for the project filter (not windowed — reflects current triage state)
active_alerts	integer	No	—	Provisional: count of open error groups with severity='critical'. Will be replaced with a fired-alert-rule counter once the alert_rule_events table is implemented.
p95_latency_ms	float	No	—	95th-percentile value from the llm.latency_ms gauge metric (LLM latency only, not general HTTP latency). Null when no latency metrics exist in the window.
tokens_24h	integer	No	—	Total llm.tokens.input + llm.tokens.output metric sum in the window
cost_24h	float	No	—	Total agents.session.total_cost_usd metric sum in the window (4 decimal places). Currently zero until billing metrics are instrumented.
avg_tokens_per_workflow	float	No	—	tokens_24h / workflows_24h; 0.0 when there are no workflows
deltas	json	No	—	Period-over-period percentage changes vs the prior equal-length window. Keys: workflows_pct, errors_pct, tokens_pct, cost_pct (float, 2 dp). 0.0 when both current and prior are zero; 100.0 when prior was zero.
error	string	No	—	Error message when RAISE_ON_QUERY_ERROR=False and query() raises
error_type	string	No	—	Python exception class name on query failure

States

State	Initial	Terminal	Success	Auto-advance	Description
done	Yes	Yes	Yes	—	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "lumen.dashboard.summary",
  "initial_data": {
    "organization_uuid": "value"
  }
}