:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from __future__ import annotations
import asyncio
from datetime import UTC, datetime, timedelta
from typing import Annotated
import structlog
from fastapi import APIRouter, Depends, Request
from pydantic import BaseModel
from llm_gateway.auth.models import AuthenticatedUser
from llm_gateway.dependencies import get_authenticated_user, resolve_quota
from llm_gateway.products.config import POSTHOG_CODE_PRODUCT
from llm_gateway.rate_limiting.billable_credits_throttle import bucket_block_applies
from llm_gateway.rate_limiting.cost_throttles import CostStatus, UserCostBurstThrottle, UserCostSustainedThrottle
from llm_gateway.rate_limiting.runner import ThrottleRunner
from llm_gateway.rate_limiting.throttles import ThrottleContext
from llm_gateway.services.billing_period_resolver import parse_iso_utc, resolve_billing_period
logger = structlog.get_logger(__name__)
usage_router = APIRouter(prefix="/v1/usage", tags=["Usage"])
class CostLimitStatus(BaseModel):
used_percent: float
# Kept on the wire for older PostHog Desktop clients whose zod schema still
# requires it. Newer clients anchor to `reset_at`; drop in a follow-up once
# the long tail of pinned clients has rolled forward.
resets_in_seconds: int
reset_at: datetime
exceeded: bool
class AiCreditsStatus(BaseModel):
exhausted: bool
# Org-level bucket spend this billing period. None means unknown (unsynced
# org, resolver fail-open) — clients must not render None as $0.
used_usd: float | None = None
limit_usd: float | None = None
breakdown: dict[str, object] | None = None
class UsageResponse(BaseModel):
product: str
user_id: int
burst: CostLimitStatus
sustained: CostLimitStatus
ai_credits: AiCreditsStatus
is_rate_limited: bool
is_pro: bool
code_usage_subscribed: bool = False
billing_period_end: datetime | None = None
def _to_cost_limit_status(status: CostStatus, now: datetime) -> CostLimitStatus:
if status.limit_usd > 0:
used_percent = min(100.0, (status.used_usd / status.limit_usd) * 100)
else:
used_percent = 100.0
return CostLimitStatus(
used_percent=round(used_percent, 1),
resets_in_seconds=status.resets_in_seconds,
reset_at=now + timedelta(seconds=status.resets_in_seconds),
exceeded=status.exceeded,
)
@usage_router.get("/{product}")
async def get_usage(
product: str,
request: Request,
user: Annotated[AuthenticatedUser, Depends(get_authenticated_user)],
) -> UsageResponse:
runner: ThrottleRunner = request.app.state.throttle_runner
quota_status, organization_billing_period = await asyncio.gather(
resolve_quota(
request,
team_id=user.team_id,
product=product,
),
resolve_billing_period(request, user.team_id),
)
now = datetime.now(tz=UTC)
context = ThrottleContext(
user=user,
product=product,
end_user_id=str(user.user_id),
code_usage_billed=quota_status.code_usage_billing_active,
credits_exhausted=quota_status.limited,
)
# The product's own credit bucket (resolve_quota resolves per bucket;
# always unlimited for unbilled products), reported under the legacy `ai_credits`
# response field — clients read `ai_credits.exhausted` regardless of bucket. Run
# through the same decision as the request-path throttle: clients gate on this
# response, so it must never disagree with what enforcement would do.
credits_exhausted = bucket_block_applies(context)
burst_status: CostLimitStatus | None = None
sustained_status: CostLimitStatus | None = None
for throttle in runner.throttles:
if isinstance(throttle, UserCostBurstThrottle):
burst_status = _to_cost_limit_status(await throttle.get_status(context), now=now)
elif isinstance(throttle, UserCostSustainedThrottle):
sustained_status = _to_cost_limit_status(await throttle.get_status(context), now=now)
if burst_status is not None and sustained_status is not None:
break
if burst_status is None or sustained_status is None:
# `limit_usd=1` is a sentinel so `_to_cost_limit_status` reports 0% used
# rather than tripping its no-throttle branch (which would surface 100%
# used + not rate-limited).
empty = CostStatus(used_usd=0, limit_usd=1, remaining_usd=1, resets_in_seconds=0, exceeded=False)
if burst_status is None:
burst_status = _to_cost_limit_status(empty, now=now)
if sustained_status is None:
sustained_status = _to_cost_limit_status(empty, now=now)
billing_period_end: datetime | None = None
raw_period_end = organization_billing_period.current_period_end if organization_billing_period else None
if raw_period_end is not None:
try:
billing_period_end = parse_iso_utc(raw_period_end)
except (ValueError, TypeError) as exc:
logger.warning(
"usage.billing_period_end_unparseable",
user_id=user.user_id,
product=product,
raw=raw_period_end,
error=str(exc),
)
billing_period_end = None
return UsageResponse(
product=product,
user_id=user.user_id,
burst=burst_status,
sustained=sustained_status,
ai_credits=AiCreditsStatus(
exhausted=credits_exhausted,
used_usd=quota_status.used_usd,
limit_usd=quota_status.limit_usd,
breakdown=quota_status.posthog_desktop_usage if product == POSTHOG_CODE_PRODUCT else None,
),
is_rate_limited=burst_status.exceeded or sustained_status.exceeded or credits_exhausted,
# The seat product is retired. No caller holds a Pro seat.
# Older PostHog Desktop builds require this field, so it stays.
is_pro=False,
code_usage_subscribed=quota_status.code_usage_billing_active,
billing_period_end=billing_period_end,
)