Usage & Spend Analytics
PickLayer records a usage_events row for every AI call your application makes. These events are the source of truth for cost attribution, quota enforcement, and the analytics views shown in the builder dashboard.
How it works
Every AI call (chat completions, responses, messages, embeddings, TTS, STT, images, video) immediately inserts a usage_events row with:
status = 'pending'and token/cost estimates (used by the guard for reservation)expires_atset 20 minutes ahead
When the call completes, the row is finalized with actual tokens, latency, and provider-reported cost. Stalled calls expire automatically and release reserved quota.
Querying usage events
For detailed event-level queries and aggregation, see management-api/usage-analytics. Key entry points:
| What you want | Where to look |
|---|---|
| Raw event stream with cost/token breakdown | usage_events GraphQL table |
| Daily cost summary per app | daily_usage_summary view |
| Per-model performance | model_performance_summary view |
| Cost by date range | cost_analysis_by_app view |
| Error breakdown | error_analysis view |
| Token volume trends | token_usage_trends view |
| Top endpoints by cost (30d) | usage_endpoint_summary_30d view |
Revenue & billing analytics
The GET /billing/analytics REST endpoint returns plan-level subscriber counts and revenue aggregates for your organization. For finer-grained revenue queries, use the billing_plan_analytics view via GraphQL — see management-api/billing.
Dashboard vs API
The Usage page in the builder console is a visual layer on top of the same GraphQL views listed above. Everything you see in the dashboard is queryable directly through the Management API.
Spending limits
You can cap both organization-level monthly spend (budget_limit, hard_cap_enabled) and application-level rate/cost limits (hard_cap_cost_per_month, hard_cap_req_per_min, etc.). The guard enforces these before each call. See the BUILDER_API_REFERENCE §18 for field names and mutation examples.