Skip to content
UltimateTeam.ai Docs

Get Kpi Snapshots

GET
/api/v1/kpi/snapshots

Query KPI daily snapshots for the current tenant.

Returns snapshots within the date range, optionally filtered by category. Annotations are included inline when present.

Args: start_date: Start of date range (inclusive). end_date: End of date range (inclusive). category: Optional category filter. user: Authenticated user context. db: Async database session.

Returns: List of KPISnapshotResponse objects.

Raises: HTTPException: 400 if start_date > end_date.

Authorizations

Parameters

Query Parameters

start_date
required

Start date (inclusive)

string format: date

Start date (inclusive)

end_date
required

End date (inclusive)

string format: date

End date (inclusive)

category
Any of:
string

Filter by category: revenue, agent_effectiveness, business_health

Responses

200

Successful Response

Array<object>

Response model for a single KPI daily snapshot.

Used by the /api/kpi/snapshots endpoint and consumed by the briefing page and KPI trend charts.

object
annotations
required
Any of:
Array<object>

A single AI-generated annotation on a KPI metric.

Created by the CEO agent during the morning brief think() step. Each annotation explains a notable change in a specific metric and suggests a follow-up action.

object
change_direction
required
string
Allowed values: up down stable
change_magnitude
required
number
metric_id
required
string
reasoning
required
string
suggested_action
required
string
category
required
string
created_at
required
string format: date-time
id
required
string format: uuid
metrics
required
object
key
additional properties
any
snapshot_date
required
string format: date
tenant_id
required
string format: uuid

422

Validation Error

object
detail
Array<object>
object
ctx
object
input
loc
required
Array
msg
required
string
type
required
string