Reference
API Reference
The Bear Lumen REST API ingests AI usage events and reads cost, attribution, and margin data back. It has 39 endpoints across 10 resource groups, all authenticated with a restricted API key over HTTPS at api.bearlumen.com/v1. Each endpoint below has its own reference page with parameters, request and response examples, and error codes.
Prefer to try requests interactively? Open the interactive API explorer. The raw OpenAPI specification is available at /openapi.json.
Connectivity
Connectivity check to verify your API key is valid and confirm the organization it is scoped to before you integrate.
GETAPI connectivity check — Returns the organization ID associated with the API key.
Usage Events
AI usage event ingestion (single and batch) for cost tracking and attribution.
POSTIngest a usage event — Records an AI usage event for cost calculation.POSTIngest a batch of usage events — Accepts an array of 1 to 100 usage events for cost calculation.
Usage Tracking
Usage event recording plus historical query and aggregation endpoints.
GETGet usage aggregation — Returns aggregated usage quantities by metric (total quantity, event count, first and last event timestamps) for volume reporting.GETGet usage events — Retrieves individual usage events recorded for the account your API key belongs to, within a date range.GETGet usage summary — Returns a high-level usage summary for a period: total event count plus per-metric totals.
Cost Data
Organization-level cost summaries, breakdowns, and trend data across all AI providers.
GETGet organization-wide cost breakdown by end user — Returns organization-wide cost aggregation grouped by end user (your customers).GETGet organization-wide cost breakdown by model — Returns organization-wide cost aggregation grouped by AI model (gpt-4o, claude-3-5-sonnet, etc.).GETGet organization-wide cost breakdown by provider — Returns organization-wide cost aggregation grouped by AI provider.GETGet cost summary — Returns the organization-wide total cost for the selected time window along with a comparison to the previous period, showing change amount and percentage to track cost trends.GETGet organization-wide cost trend — Returns organization-wide time-series cost data.
End User Costs
Per-user cost analysis scoped by your external user ID. Understand spend concentration and per-customer unit economics.
GETGet cost breakdown by dimension for a specific end-user — Returns cost aggregation grouped by a metadata dimension key for the specified end-user.GETGet cost breakdown by model for a specific end-user — Returns cost aggregation grouped by AI model for the specified end-user.GETGet cost breakdown by provider for a specific end-user — Returns cost aggregation grouped by AI provider for the specified end-user.GETGet end user cost summary — Returns cost summary for the specified end-user with comparison to the previous period.GETGet cost trend for a specific end-user — Returns time-series cost data with adaptive granularity for the specified end-user.
Margin Data
Margin and profitability analysis comparing AI costs against revenue.
GETGet margin by end user — Returns margin data for each of your end users (the customers you attribute usage and revenue to), sorted by profitability with the least profitable first so unprofitable end users surface at the top.GETGet margin summary — Returns total revenue, cost, and margin for the organization with warnings about unattributed data and profitability classification.GETGet margin trend — Returns time-series margin data (revenue - cost) with adaptive granularity: - <= 30 days: daily - 31-90 days: weekly - > 90 days: monthly Periods with no revenue and no cost activity are omitted from data_points rather than returned as zero values.
Attribution Data
Dimensional cost analysis grouped by model, provider, feature, agent, or workflow.
GETList unique agent IDs — Returns every distinct agent_id value from usage event metadata for the given date range, sorted alphabetically.GETGet cost breakdown by agent — Returns cost aggregation grouped by agent_id from usage event metadata.GETGet cost breakdown by dimension — Returns cost aggregation grouped by any metadata dimension key.GETGet cost per declared outcome — Returns the true cost per unit of value: for every outcome your spans declare (see the tracing guide), completed, failed, and unresolved units side by side.GETGet cost breakdown by workflow — Returns cost aggregation grouped by workflow_id from usage event metadata.GETList distinct dimension keys — Returns every distinct metadata dimension key from usage events within a date range, sorted alphabetically.GETList unique dimension values — Returns every distinct value of a metadata dimension key in the date range, sorted alphabetically.GETCompare session types — Returns a per-session-type cost comparison with a cost efficiency ratio.GETGet session cost breakdown — Returns per-session cost totals, ordered by total cost descending.GETGet session detail — Returns a per-feature cost breakdown for one session.GETGet session call tree — Reconstructs one session's span call tree: one node per span with its own cost, its subtree cost (the span plus every descendant), and its nested children, so you can see which branch of a multi-agent run spent the money.GETGet attribution time-series — Returns time-bucketed multi-series cost data grouped by any metadata dimension key.GETList unique workflow IDs — Returns every distinct workflow_id value from usage event metadata for the given date range, sorted alphabetically.
Dimension Data
Custom dimension definitions and cost breakdowns by user-defined categories.
GETGet cost breakdown by dimension — Returns cost aggregated by a specific custom dimension (e.g., "team", "region").GETGet cost trend by dimension — Returns time-series cost data with adaptive granularity based on date range.GETGet dimension definitions — Returns all dimension definitions for the organization.GETGet numeric dimension summary — Returns a single aggregated numeric value (SUM/AVG/MIN/MAX) for a numeric custom dimension.GETGet numeric dimension trend — Returns time-bucketed aggregated numeric values (SUM/AVG/MIN/MAX) for a numeric custom dimension.
Rate Cards
Effective per-model rates for client-side cost estimation. The SDK budget feature refreshes its local price table from here; the server-side ledger is the record.
GETGet the rate estimation table — Returns your organization's effective per-model rates in USD per million tokens, for client-side budget estimation; the server-side ledger is the record.
Insights
AI-optimized statistical summary: period-over-period totals, distributions, top movers, and correlations.
GETGet insights summary — Returns period-over-period totals, population distributions, top movers with z-scores, margin outliers, and cross-metric correlations.