Skip to content

: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.

5.9 KB
Raw Blame
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,
    )