Analytics API

Table of Contents

• upsquad/analytics/v1/analytics.proto

  • ActivityFeedEntry

  • AgentUtilizationEntry

  • Anomaly

  • CostBreakdownEntry

  • GenerateBriefingRequest

  • GenerateBriefingResponse

  • GetAgentUtilizationRequest

  • GetAgentUtilizationResponse

  • GetAnomaliesRequest

  • GetAnomaliesResponse

  • GetCostBreakdownRequest

  • GetCostBreakdownResponse

  • GetDashboardKPIsRequest

  • GetDashboardKPIsResponse

  • GetTeamSpendRequest

  • GetTeamSpendResponse

  • GetTokenUsageTimeSeriesRequest

  • GetTokenUsageTimeSeriesResponse

  • GetWorkflowMetricsRequest

  • GetWorkflowMetricsResponse

  • ListActivityFeedRequest

  • ListActivityFeedResponse

  • PendingAction

  • TeamSpend

  • TokenUsageDataPoint

  • GetTeamSpendRequest.Period

  • Granularity

  • GroupBy

  • Scope

  • AnalyticsService

• Scalar Value Types

Top

upsquad/analytics/v1/analytics.proto

ActivityFeedEntry

ActivityFeedEntry is one row from the clearance-projected activity feed. Added by LLD #855.

Field	Type	Label	Description
action_id	string		action_id is the agent_audit_log row id.
agent_id	string		agent_id is the agent that produced the action.
agent_name	string		agent_name is the display name of the agent (joined from agents/members).
action_type	string		action_type is the audit_action_type enum rendered as string.
summary	string		summary is a short human-readable derived from the detail JSONB.
created_at	google.protobuf.Timestamp		created_at is the wall-clock of the audit_log row.
team_id	string		team_id of the acting agent at the time of the action.
pillar_id	string		pillar_id of the acting agent at the time of the action.

AgentUtilizationEntry

AgentUtilizationEntry describes one agent's recent activity.

Field	Type	Label	Description
agent_id	string		agent_id is the UUID of the agent.
agent_name	string		agent_name is the human-readable agent name.
events_24h	int64		events_24h is the number of context events in the last 24 hours.
last_active	google.protobuf.Timestamp		last_active is the timestamp of the most recent event.
status	string		status is the derived health status: healthy, degraded, or idle.

Anomaly

Anomaly describes a detected operational anomaly.

Field	Type	Label	Description
type	string		type is the anomaly category: error_spike, cost_overrun, stalled_workflow, unusual_consumption.
severity	string		severity is the anomaly severity: warning, critical.
title	string		title is a short human-readable summary.
description	string		description is a detailed explanation.
entity_id	string		entity_id is the UUID of the affected entity (agent, workflow, etc.).
detected_at	google.protobuf.Timestamp		detected_at is when the anomaly was detected.

CostBreakdownEntry

CostBreakdownEntry is one grouped cost entry.

Field	Type	Label	Description
entity_name	string		entity_name is the human-readable name (agent name or model ID).
entity_id	string		entity_id is the UUID (agent_id) or model string.
tokens	int64		tokens is the total tokens consumed by this entity.
cost	double		cost is the estimated cost in USD.
percentage	double		percentage is this entity's share of total cost (0-100).

GenerateBriefingRequest

GenerateBriefingRequest specifies the briefing window.

Field	Type	Label	Description
since	google.protobuf.Timestamp		since is the start of the briefing window (default: midnight UTC).

GenerateBriefingResponse

GenerateBriefingResponse contains the executive briefing.

Field	Type	Label	Description
overnight_summary	string		overnight_summary is a text summary of overnight activity.
pending_actions	PendingAction	repeated	pending_actions is the list of items requiring attention.
agent_health_summary	string		agent_health_summary is a text summary of agent health status.
cost_trend_summary	string		cost_trend_summary is a text summary of cost trends.

GetAgentUtilizationRequest

GetAgentUtilizationRequest filters agent utilization data.

Field	Type	Label	Description
pillar_id	string		pillar_id optionally filters agents by pillar.
team_id	string		team_id optionally filters agents by team.

GetAgentUtilizationResponse

GetAgentUtilizationResponse contains agent utilization data.

Field	Type	Label	Description
agents	AgentUtilizationEntry	repeated	agents is the list of agent utilization entries.

GetAnomaliesRequest

GetAnomaliesRequest specifies the lookback window for anomaly detection.

Field	Type	Label	Description
lookback_hours	int32		lookback_hours is how far back to check (default 24).

GetAnomaliesResponse

GetAnomaliesResponse contains detected anomalies.

Field	Type	Label	Description
anomalies	Anomaly	repeated	anomalies is the list of detected anomalies.

GetCostBreakdownRequest

GetCostBreakdownRequest filters cost breakdown data.

Field	Type	Label	Description
group_by	GroupBy		group_by controls whether costs are grouped by agent or model.
start_date	google.protobuf.Timestamp		start_date is the inclusive start of the query range.
end_date	google.protobuf.Timestamp		end_date is the inclusive end of the query range.

GetCostBreakdownResponse

GetCostBreakdownResponse contains the grouped cost entries.

Field	Type	Label	Description
entries	CostBreakdownEntry	repeated	entries is the list of cost breakdown items.

GetDashboardKPIsRequest

GetDashboardKPIsRequest filters the KPI aggregation window. Added by LLD #855.

Field	Type	Label	Description
window_hours	int32		window_hours is the KPI aggregation window. Default 24, max 168 (7d).

GetDashboardKPIsResponse

GetDashboardKPIsResponse returns the L1 dashboard KPI summary. Added by LLD #855.

Field	Type	Label	Description
active_agents	int64		active_agents is the distinct count of agents active in the window.
workflows_running	int64		workflows_running is the count of workflow runs currently in-flight.
pending_approvals	int64		pending_approvals is the count of actions awaiting approval.
tokens_consumed	int64		tokens_consumed is the sum of LLM tokens consumed in the window.
cost_usd	double		cost_usd is the sum of cost in USD for the window.
context_events	int64		context_events is the count of context_events produced in the window.
generated_at	google.protobuf.Timestamp		generated_at is the server wall-clock at aggregation time.

GetTeamSpendRequest

GetTeamSpendRequest specifies the period for team-level spend rollup.

Field	Type	Label	Description
period	GetTeamSpendRequest.Period		period selects the aggregation window. Defaults to MONTH_TO_DATE.

GetTeamSpendResponse

GetTeamSpendResponse contains the per-team spend rollups.

Field	Type	Label	Description
teams	TeamSpend	repeated	teams is the list of per-team spend entries, ordered by spent DESC so the budget-burn widget shows the heaviest spenders first.

GetTokenUsageTimeSeriesRequest

GetTokenUsageTimeSeriesRequest filters token usage data.

Field	Type	Label	Description
scope_level	Scope		scope_level filters by hierarchical scope (org, pillar, team, agent).
scope_id	string		scope_id is the UUID of the entity at the selected scope level.
granularity	Granularity		granularity controls hour, day or week bucketing. HOUR (GAP-4 #1073) is capped server-side at 168 buckets / 7 days; wider ranges with HOUR are rejected as InvalidArgument.
start_date	google.protobuf.Timestamp		start_date is the inclusive start of the query range.
end_date	google.protobuf.Timestamp		end_date is the inclusive end of the query range.

GetTokenUsageTimeSeriesResponse

GetTokenUsageTimeSeriesResponse contains the time-series data.

Field	Type	Label	Description
data_points	TokenUsageDataPoint	repeated	data_points is the ordered list of time-series entries.

GetWorkflowMetricsRequest

GetWorkflowMetricsRequest filters workflow metrics.

Field	Type	Label	Description
start_date	google.protobuf.Timestamp		start_date is the inclusive start of the query range.
end_date	google.protobuf.Timestamp		end_date is the inclusive end of the query range.

GetWorkflowMetricsResponse

GetWorkflowMetricsResponse contains aggregate workflow statistics.

Field	Type	Label	Description
total_runs	int64		total_runs is the number of workflow runs in the period.
completed	int64		completed is the number of successfully completed runs.
failed	int64		failed is the number of failed runs.
avg_duration_seconds	double		avg_duration_seconds is the average run duration.
completion_rate	double		completion_rate is completed/total_runs as a percentage (0-100).
pending_approvals	int64		pending_approvals is the number of actions awaiting approval.

ListActivityFeedRequest

ListActivityFeedRequest bounds and paginates the activity feed query. Added by LLD #855.

Field	Type	Label	Description
page_size	int32		page_size is the max entries returned per page. Default 20, max 100.
cursor	string		cursor is an opaque base64 token from a prior response's next_cursor. Empty string means the caller wants the first page.
since	google.protobuf.Timestamp		since optionally bounds the oldest entry in the result (inclusive).

ListActivityFeedResponse

ListActivityFeedResponse is a paginated activity-feed page. Added by LLD #855.

Field	Type	Label	Description
entries	ActivityFeedEntry	repeated	entries is the list of activity-feed rows for this page, newest first.
next_cursor	string		next_cursor is the token to pass as cursor on the next call. Empty when this is the last page.

PendingAction

PendingAction describes an action that requires attention.

Field	Type	Label	Description
action_id	string		action_id is the UUID of the pending item.
action_type	string		action_type describes the kind of action (approval, review, etc.).
description	string		description is a human-readable summary of what needs to be done.
entity_id	string		entity_id is the UUID of the related entity.
created_at	google.protobuf.Timestamp		created_at is when the action was created.

TeamSpend

TeamSpend is one team's spend rollup for the requested period.

Note: amounts are reported as USD double to remain consistent with the existing CostBreakdownEntry.cost field on this same service. The upstream issue (#1036) suggested google.type.Money but the proto module does not currently depend on the googleapis BSR module and adding it solely for this RPC would dilute the dependency surface for one widget. The deviation is documented in the PR body so the next pass that legitimately needs Money (e.g. multi-currency billing readouts) can introduce the dep without coupling to GAP-3.

Field	Type	Label	Description
team_id	string		team_id is the org_units.id of the team (unit_type='team').
team_name	string		team_name is the display name of the team.
spent	double		spent is the total spend in USD across the requested period.
cap	double		cap is the team's monthly spend cap in USD. Computed as the sum of agent_budgets.monthly_cost_cap for every active agent currently attached to the team (so a team with no caps reports 0). Cap is always reported as the monthly figure regardless of period to match the dashboard widget's "Burned X of Y/mo" semantics.
forecast	double		forecast is the projected end-of-period spend in USD using a linear extrapolation from period-to-date. Forecast == spent for the PERIOD_LAST_30_DAYS period because the window is already a full 30-day rolling sum (no extrapolation needed).
spent_pct	double		spent_pct is spent / cap * 100, in [0, +inf). Reported as 0 when cap == 0 to avoid div-by-zero spikes on uncapped teams.
over_cap	bool		over_cap is true when spent > cap and cap > 0.

TokenUsageDataPoint

TokenUsageDataPoint is one time-series data point.

Field	Type	Label	Description
date	google.protobuf.Timestamp		date is the start of the time bucket.
input_tokens	int64		input_tokens is the total input tokens in this bucket.
output_tokens	int64		output_tokens is the total output tokens in this bucket.
total_tokens	int64		total_tokens is input_tokens + output_tokens.
cost	double		cost is the estimated cost in USD for this bucket.

GetTeamSpendRequest.Period

Period selects the aggregation window for the spend rollup.

Name	Number	Description
PERIOD_UNSPECIFIED	0	PERIOD_UNSPECIFIED defaults to PERIOD_MONTH_TO_DATE.
PERIOD_MONTH_TO_DATE	1	PERIOD_MONTH_TO_DATE aggregates from the first of the current calendar month (UTC, midnight) through the moment of the request.
PERIOD_LAST_30_DAYS	2	PERIOD_LAST_30_DAYS aggregates from now-30d through the moment of the request. Used for stable rolling-window comparisons that do not reset on the first of the month.

Granularity

Granularity defines the time bucketing for time-series data.

Name	Number	Description
GRANULARITY_UNSPECIFIED	0	GRANULARITY_UNSPECIFIED defaults to daily.
GRANULARITY_DAY	1	GRANULARITY_DAY groups data by calendar day.
GRANULARITY_WEEK	2	GRANULARITY_WEEK groups data by ISO week.
GRANULARITY_HOUR	3	GRANULARITY_HOUR groups data by hour. Range is capped at 168 buckets (7 days) server-side per GAP-4 (#1073) — over-cap requests are rejected with InvalidArgument so the dashboard sparkline can never pull an unbounded series.

GroupBy

GroupBy defines the grouping dimension for cost breakdowns.

Name	Number	Description
GROUP_BY_UNSPECIFIED	0	GROUP_BY_UNSPECIFIED defaults to agent.
GROUP_BY_AGENT	1	GROUP_BY_AGENT groups costs by agent.
GROUP_BY_MODEL	2	GROUP_BY_MODEL groups costs by LLM model.

Scope

Scope defines the hierarchical filter level for analytics queries.

Name	Number	Description
SCOPE_UNSPECIFIED	0	SCOPE_UNSPECIFIED defaults to org-level.
SCOPE_ORG	1	SCOPE_ORG queries across the entire organisation.
SCOPE_PILLAR	2	SCOPE_PILLAR queries within a single pillar.
SCOPE_TEAM	3	SCOPE_TEAM queries within a single team.
SCOPE_AGENT	4	SCOPE_AGENT queries for a single agent.

AnalyticsService

AnalyticsService exposes aggregated analytics for the UpsQuad dashboard. All RPCs are scoped to the caller's tenant organisation via JWT-derived scope claims injected by the scope middleware.

Method Name	Request Type	Response Type	Description
GetTokenUsageTimeSeries	GetTokenUsageTimeSeriesRequest	GetTokenUsageTimeSeriesResponse	GetTokenUsageTimeSeries returns token usage grouped by day or week.
GetCostBreakdown	GetCostBreakdownRequest	GetCostBreakdownResponse	GetCostBreakdown returns cost data grouped by agent or model.
GetTeamSpend	GetTeamSpendRequest	GetTeamSpendResponse	GetTeamSpend returns per-team current spend, monthly cap, and a linear forecast for the requested period. Powers the dashboard "Budget burn by team" widget and the per-team rows on the org page. See GAP-3 / issue #1036.
GetAgentUtilization	GetAgentUtilizationRequest	GetAgentUtilizationResponse	GetAgentUtilization returns recent activity metrics for each agent.
GetWorkflowMetrics	GetWorkflowMetricsRequest	GetWorkflowMetricsResponse	GetWorkflowMetrics returns aggregate workflow run statistics.
GetAnomalies	GetAnomaliesRequest	GetAnomaliesResponse	GetAnomalies detects operational anomalies from recent data.
GenerateBriefing	GenerateBriefingRequest	GenerateBriefingResponse	GenerateBriefing produces an executive summary from overnight data.
GetDashboardKPIs	GetDashboardKPIsRequest	GetDashboardKPIsResponse	GetDashboardKPIs returns the L1 KPI-bar summary for the caller's scope. Added by LLD #855 (HLD #831, PRD #824). Uncached for MVP.
ListActivityFeed	ListActivityFeedRequest	ListActivityFeedResponse	ListActivityFeed returns a clearance-projected slice of agent_audit_log. Projection is driven by the caller's session-local app.clearance GUC (see ADR #853); callers cannot forge a higher projection level. Added by LLD #855 (HLD #831, PRD #824).

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)