Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(gateway): let workspace admins read their usage

Petr Bauch3d44947832b6
diff --git a/core/switch_core/gateway/app.py b/core/switch_core/gateway/app.py
index 038baf073..9d57c4cb9 100644
--- a/core/switch_core/gateway/app.py
+++ b/core/switch_core/gateway/app.py
@@ -26,6 +26,7 @@ from switch_core.db.stores.room_group_store import RoomGroupStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.server_connector_store import ServerConnectorStore
from switch_core.db.stores.template_store import TemplateStore
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway.agent_sessions import router as agent_sessions_router
from switch_core.gateway.agents import router as agents_router
@@ -71,6 +72,7 @@ def create_gateway_app(
api_key_store: ApiKeyStore,
invitation_store: InvitationStore,
template_store: TemplateStore,
+ usage_store: UsageStore,
resource_service: ResourceService,
protocol: ProtocolService,
install_service: MessagingInstallService | None,
@@ -93,6 +95,7 @@ def create_gateway_app(
api_key_store=api_key_store,
invitation_store=invitation_store,
template_store=template_store,
+ usage_store=usage_store,
resource_service=resource_service,
protocol=protocol,
install_service=install_service,
diff --git a/core/switch_core/gateway/dependencies.py b/core/switch_core/gateway/dependencies.py
index 4e5aecbd4..4b6098e96 100644
--- a/core/switch_core/gateway/dependencies.py
+++ b/core/switch_core/gateway/dependencies.py
@@ -29,6 +29,7 @@ from switch_core.db.stores.room_group_store import RoomGroupStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.server_connector_store import ServerConnectorStore
from switch_core.db.stores.template_store import TemplateStore
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.db.stores.user_store import UserStore
from switch_core.room_service import RoomService
from switch_core.rooms_yaml import RoomYamlService
@@ -55,6 +56,7 @@ def init_dependencies(
api_key_store: ApiKeyStore,
invitation_store: InvitationStore,
template_store: TemplateStore,
+ usage_store: UsageStore,
resource_service: ResourceService,
protocol: ProtocolService,
install_service: MessagingInstallService | None,
@@ -76,6 +78,7 @@ def init_dependencies(
_state["api_key_store"] = api_key_store
_state["invitation_store"] = invitation_store
_state["template_store"] = template_store
+ _state["usage_store"] = usage_store
_state["resource_service"] = resource_service
_state["protocol"] = protocol
_state["install_service"] = install_service
@@ -194,6 +197,10 @@ def get_invitation_store() -> InvitationStore:
return _state["invitation_store"] # type: ignore[no-any-return]
+def get_usage_store() -> UsageStore:
+ return _state["usage_store"] # type: ignore[no-any-return]
+
+
def get_connector_lifecycle() -> ServerSideConnectorLifecycleService:
return _state["connector_lifecycle"] # type: ignore[no-any-return]
diff --git a/core/switch_core/gateway/schemas.py b/core/switch_core/gateway/schemas.py
index d8178781c..f3700dd5e 100644
--- a/core/switch_core/gateway/schemas.py
+++ b/core/switch_core/gateway/schemas.py
@@ -721,6 +721,21 @@ class MemberDetail(BaseModel):
created_at: str
+class UsageTotalResponse(BaseModel):
+ """One consumer's total of one metric over the requested window.
+
+ `client_name` and `client_type` are null when the client has since been
+ deleted; what it spent still counts against the workspace.
+ """
+
+ metric: str
+ client_id: str
+ client_name: str | None
+ client_type: str | None
+ model: str
+ amount: int
+
+
class MemberUpdateRequest(BaseModel):
role: str
diff --git a/core/switch_core/gateway/tenants.py b/core/switch_core/gateway/tenants.py
index 4b2065dac..de91b37ce 100644
--- a/core/switch_core/gateway/tenants.py
+++ b/core/switch_core/gateway/tenants.py
@@ -6,7 +6,7 @@ import re
from datetime import UTC, datetime, timedelta
from typing import Annotated
-from fastapi import APIRouter, Depends, HTTPException, Response
+from fastapi import APIRouter, Depends, HTTPException, Query, Response
from sqlalchemy import select
from sqlalchemy.exc import DBAPIError, IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@@ -22,6 +22,7 @@ from switch_core.db.stores.invitation_store import (
InvitationNotUsableError,
InvitationStore,
)
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway.auth import (
AuthenticatedCaller,
@@ -47,6 +48,7 @@ from switch_core.gateway.dependencies import (
get_session,
get_session_factory,
get_system_session,
+ get_usage_store,
get_user_store,
)
from switch_core.gateway.schemas import (
@@ -59,6 +61,7 @@ from switch_core.gateway.schemas import (
SessionUserResponse,
TenantCreateRequest,
TenantMembershipResponse,
+ UsageTotalResponse,
)
from switch_core.telemetry import emit_safely
from switch_core.telemetry.ages import age_hours
@@ -429,6 +432,44 @@ async def create_invitation(
return InvitationCreateResponse(token=token, **_invitation_fields(invitation))
[email protected]("/tenants/{tenant_id}/usage")
+async def get_usage(
+ tenant_id: str,
+ since: Annotated[datetime, Query()],
+ until: Annotated[datetime, Query()],
+ session: Annotated[AsyncSession, Depends(get_session)],
+ usage_store: Annotated[UsageStore, Depends(get_usage_store)],
+ _user: Annotated[User, Depends(require_tenant_admin)],
+) -> list[UsageTotalResponse]:
+ """The bound tenant's usage per metric, consumer and model over `[since, until)`.
+
+ `owner`/`admin` only. Usage is counted in whole UTC hours, so `since` is
+ widened to the start of its hour. Both bounds must carry a timezone: a
+ naive time would be read in the server's zone and quietly shift the window.
+ """
+ _require_bound_tenant(tenant_id)
+ if since.tzinfo is None or until.tzinfo is None:
+ raise HTTPException(
+ status_code=400, detail="since and until must include a timezone offset"
+ )
+ if since >= until:
+ raise HTTPException(status_code=400, detail="since must be before until")
+ totals = await usage_store.totals(
+ session, tenant_id=tenant_id, since=since, until=until
+ )
+ return [
+ UsageTotalResponse(
+ metric=t.metric,
+ client_id=t.client_id,
+ client_name=t.client_name,
+ client_type=t.client_type,
+ model=t.model,
+ amount=t.amount,
+ )
+ for t in totals
+ ]
+
+
@router.get("/tenants/{tenant_id}/invitations")
async def list_invitations(
tenant_id: str,
diff --git a/core/switch_core/main.py b/core/switch_core/main.py
index 389a00684..6ae94c806 100644
--- a/core/switch_core/main.py
+++ b/core/switch_core/main.py
@@ -644,6 +644,7 @@ async def run(config: SwitchConfig) -> None:
api_key_store=api_key_store,
invitation_store=invitation_store,
template_store=template_store,
+ usage_store=usage_store,
resource_service=resource_service,
protocol=protocol,
install_service=install_service,
diff --git a/core/tests/switch_core/gateway/test_tenant_api_routes.py b/core/tests/switch_core/gateway/test_tenant_api_routes.py
index 8dcd19bc1..6997b7cc1 100644
--- a/core/tests/switch_core/gateway/test_tenant_api_routes.py
+++ b/core/tests/switch_core/gateway/test_tenant_api_routes.py
@@ -33,12 +33,14 @@ from switch_core.db.models import (
Invitation,
Tenant,
TenantMember,
+ UsageMetric,
User,
)
from switch_core.db.session_scope import tenant_session
from switch_core.db.stores.agent_store import AgentStore
from switch_core.db.stores.api_key_store import ApiKeyStore
from switch_core.db.stores.invitation_store import InvitationStore
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway import dependencies as gw_deps
from switch_core.gateway.auth import create_jwt
@@ -89,6 +91,7 @@ def _app(
app.dependency_overrides[gw_deps.get_agent_store] = lambda: AgentStore()
app.dependency_overrides[gw_deps.get_api_key_store] = lambda: ApiKeyStore()
app.dependency_overrides[gw_deps.get_invitation_store] = lambda: InvitationStore()
+ app.dependency_overrides[gw_deps.get_usage_store] = lambda: UsageStore()
app.dependency_overrides[gw_deps.get_protocol] = lambda: _fake_protocol()
app.dependency_overrides[gw_deps.get_client_lifecycle] = lambda: (
client_lifecycle or _FakeClientLifecycle(session_factory)
@@ -1120,3 +1123,122 @@ class TestMemberRoutes:
response = await client.delete(f"/tenants/{TENANT_A}/members/{target_id}")
assert response.status_code == 403
+
+
+def _window() -> dict[str, str]:
+ now = datetime.now(UTC)
+ return {
+ "since": (now - timedelta(hours=1)).isoformat(),
+ "until": (now + timedelta(hours=1)).isoformat(),
+ }
+
+
+class TestUsageRoute:
+ async def _spend(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ tenant_id: str,
+ amount: int,
+ ) -> None:
+ async with tenant_session(session_factory, tenant_id) as session:
+ await UsageStore().record(
+ session,
+ tenant_id=tenant_id,
+ metric=UsageMetric.MESSAGES,
+ client_id=f"client-of-{tenant_id}",
+ model="",
+ amount=amount,
+ )
+ await session.commit()
+
+ async def test_an_admin_sees_their_workspaces_usage_only(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ await _make_tenant(session_factory, TENANT_A)
+ await _make_tenant(session_factory, TENANT_B)
+ await self._spend(session_factory, TENANT_A, 3)
+ await self._spend(session_factory, TENANT_B, 40)
+ user_id = await _make_member(
+ session_factory, name="usage-admin", tenant_id=TENANT_A, role="admin"
+ )
+ token = _token(user_id, "[email protected]", TENANT_A)
+
+ async with _client(_app(session_factory), token) as client:
+ response = await client.get(f"/tenants/{TENANT_A}/usage", params=_window())
+
+ assert response.status_code == 200
+ assert response.json() == [
+ {
+ "metric": "messages",
+ "client_id": f"client-of-{TENANT_A}",
+ "client_name": None,
+ "client_type": None,
+ "model": "",
+ "amount": 3,
+ }
+ ]
+
+ async def test_a_plain_member_cannot_read_usage(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ await _make_tenant(session_factory, TENANT_A)
+ user_id = await _make_member(
+ session_factory, name="usage-member", tenant_id=TENANT_A, role="member"
+ )
+ token = _token(user_id, "[email protected]", TENANT_A)
+
+ async with _client(_app(session_factory), token) as client:
+ response = await client.get(f"/tenants/{TENANT_A}/usage", params=_window())
+
+ assert response.status_code == 403
+
+ async def test_an_admin_of_a_cannot_read_bs_usage(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ await _make_tenant(session_factory, TENANT_A)
+ await _make_tenant(session_factory, TENANT_B)
+ user_id = await _make_member(
+ session_factory, name="usage-snoop", tenant_id=TENANT_A, role="admin"
+ )
+ token = _token(user_id, "[email protected]", TENANT_A)
+
+ async with _client(_app(session_factory), token) as client:
+ response = await client.get(f"/tenants/{TENANT_B}/usage", params=_window())
+
+ assert response.status_code == 403
+
+ async def test_a_window_without_a_timezone_is_refused(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ await _make_tenant(session_factory, TENANT_A)
+ user_id = await _make_member(
+ session_factory, name="usage-naive", tenant_id=TENANT_A, role="owner"
+ )
+ token = _token(user_id, "[email protected]", TENANT_A)
+
+ async with _client(_app(session_factory), token) as client:
+ response = await client.get(
+ f"/tenants/{TENANT_A}/usage",
+ params={"since": "2026-01-01T00:00:00", "until": "2026-01-02T00:00:00"},
+ )
+
+ assert response.status_code == 400
+ assert "timezone" in response.json()["detail"]
+
+ async def test_an_empty_window_is_refused(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ await _make_tenant(session_factory, TENANT_A)
+ user_id = await _make_member(
+ session_factory, name="usage-empty", tenant_id=TENANT_A, role="owner"
+ )
+ token = _token(user_id, "[email protected]", TENANT_A)
+ window = _window()
+
+ async with _client(_app(session_factory), token) as client:
+ response = await client.get(
+ f"/tenants/{TENANT_A}/usage",
+ params={"since": window["until"], "until": window["since"]},
+ )
+
+ assert response.status_code == 400