Insights API
Get insights summary
Returns period-over-period totals, population distributions, top movers with z-scores, margin outliers, and cross-metric correlations. Call it with a GET request to /insights/summary, authenticated with a restricted API key and the "costs:read", "revenue:read" scopes.
GET https://api.bearlumen.com/v1/insights/summary
Returns period-over-period totals, population distributions, top movers with z-scores, margin outliers, and cross-metric correlations. Designed for AI agent consumption: pure statistical data, no narrative. Use this endpoint when you need distributions, z-scored top movers, margin outliers, and correlations; use /cost-data/summary for a simple cost rollup with period comparison. All monetary values are USD. Totals (cost, revenue), top-mover costs, and distribution statistics are expressed in dollars; unmappedSpend fields are integer cents. Requests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.
Authentication and scopes
Authenticate with a restricted API key in the Authorization: Bearer <key> header. This endpoint requires the costs:read, revenue:read scopes.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
start | query | string | Yes | Start of date range (ISO 8601, inclusive). Filters on event invocation time, evaluated in UTC. The requested range must not exceed 365 days; longer ranges return 400. |
end | query | string | Yes | End of date range (ISO 8601, exclusive). Filters on event invocation time, evaluated in UTC. The requested range must not exceed 365 days; longer ranges return 400. |
include | query | string | No | Optional sections to compute. Supported value: distributions. Unrecognized values are ignored. When omitted, the distributions field is null. |
limit | query | number (double) | No | Maximum number of top movers per category. Default 5. Values outside 1-50 are clamped to the nearest bound, not rejected; non-integer values are accepted. |
prior_start | query | string | No | Explicit prior period start (ISO 8601). Must be provided together with prior_end; if either is omitted, the prior period defaults to the window of equal length immediately preceding start. |
prior_end | query | string | No | Explicit prior period end (ISO 8601, exclusive). Must be provided together with prior_start; if either is omitted, the prior period defaults to the window of equal length immediately preceding start. |
Response example
Success response (200):
JSON
{
"correlations": {
"cost_vs_request_volume": 0.52,
"margin_vs_model_mix": -0.86
},
"distributions": {
"cost_per_end_user": {
"gini": 0.48,
"mean": 1529.23,
"median": 1543.26,
"p25": 244.89,
"p75": 2508.53,
"p90": 3024.56,
"p99": 3394.06,
"skewness": 0.1,
"std_dev": 1304.35,
"top_decile_share": 37.4
},
"cost_per_request": {
"mean": 349.1366,
"median": 269.1531,
"p25": 34.3266,
"p75": 442.7363,
"p90": 771.63,
"p99": 1063.6305,
"std_dev": 379.9823
},
"daily_cost": {
"cv": 1.072,
"max": 1204.63,
"mean": 295.98,
"median": 236.04,
"min": 0.48,
"std_dev": 317.44,
"trend": {
"direction": "increasing",
"r2": 0.114,
"slope": 11.9779
}
},
"margin_per_end_user": {
"below_zero_count": 1,
"mean": 11.6,
"median": 14,
"p25": -10.1,
"p75": 34.5,
"p90": 46.8,
"p99": 54.2,
"skewness": -0.1,
"std_dev": 36.5
},
"requests_per_end_user": {
"mean": 7,
"median": 3,
"p25": 2,
"p75": 7,
"p90": 16,
"p99": 23,
"std_dev": 7.9
}
},
"margin_outliers": [],
"period": {
"current": {
"end": "2026-06-01T00:00:00.000Z",
"start": "2026-01-01T00:00:00.000Z"
},
"prior": {
"end": "2026-01-01T00:00:00.000Z",
"start": "2025-08-01T00:00:00.000Z"
}
},
"top_movers": {
"by_custom_dimension": {
"batch_size": [
{
"change_percent": null,
"cost": 7043.47,
"end_user_count": 5,
"prior": 0,
"request_count": 34,
"share_percent": 76.8,
"value": "Unassigned",
"z_score": 3.1
},
{
"change_percent": -100,
"cost": 0,
"end_user_count": 0,
"prior": 851.13,
"request_count": 0,
"share_percent": 0,
"value": "104",
"z_score": -0.8
},
{
"change_percent": null,
"cost": 612.44,
"end_user_count": 0,
"prior": 0,
"request_count": 1,
"share_percent": 6.7,
"value": "128",
"z_score": -0.1
},
{
"change_percent": null,
"cost": 484.72,
"end_user_count": 0,
"prior": 0,
"request_count": 1,
"share_percent": 5.3,
"value": "256",
"z_score": -0.1
},
{
"change_percent": -100,
"cost": 0,
"end_user_count": 0,
"prior": 412.55,
"request_count": 0,
"share_percent": 0,
"value": "56",
"z_score": -0.6
}
],
"environment": [
{
"change_percent": null,
"cost": 7101.74,
"end_user_count": 5,
"prior": 0,
"request_count": 35,
"share_percent": 77.4,
"value": "Unassigned",
"z_score": 1.7
},
{
"change_percent": 107,
"cost": 1761.75,
"end_user_count": 0,
"prior": 851.13,
"request_count": 4,
"share_percent": 19.2,
"value": "production",
"z_score": -0.4
},
{
"change_percent": -34.6,
"cost": 269.71,
"end_user_count": 0,
"prior": 412.55,
"request_count": 2,
"share_percent": 2.9,
"value": "staging",
"z_score": -0.7
},
{
"change_percent": null,
"cost": 42.19,
"end_user_count": 0,
"prior": 0,
"request_count": 1,
"share_percent": 0.5,
"value": "development",
"z_score": -0.6
}
]
},
"by_end_user": [
{
"change_percent": null,
"cost": 3435.12,
"margin": 55,
"margin_percentile": 100,
"model_mix": {
"claude-3-5-sonnet": 32.8,
"gemini-2.0-flash": 5.6,
"gpt-4o": 50.6,
"gpt-4o-mini": 11.1
},
"percentile": 100,
"prior": 0,
"share_percent": 37.4,
"value": "user_fixture_a",
"z_score": 1.7
},
{
"change_percent": null,
"cost": 2192.15,
"margin": 14,
"margin_percentile": 66.7,
"model_mix": {
"claude-3-5-sonnet": 45,
"gpt-4o": 55
},
"percentile": 66.7,
"prior": 0,
"share_percent": 23.9,
"value": "user_fixture_b",
"z_score": 0.7
},
{
"change_percent": 106.9,
"cost": 2613.99,
"margin": null,
"margin_percentile": null,
"model_mix": {},
"percentile": 83.3,
"prior": 1263.68,
"share_percent": 28.5,
"value": "Unassigned",
"z_score": 0
},
{
"change_percent": null,
"cost": 894.37,
"margin": -34.3,
"margin_percentile": 33.3,
"model_mix": {
"gemini-2.0-flash": 42.7,
"gpt-4o-mini": 57.3
},
"percentile": 50,
"prior": 0,
"share_percent": 9.7,
"value": "user_fixture_c",
"z_score": -0.4
},
{
"change_percent": null,
"cost": 28.39,
"margin": null,
"margin_percentile": null,
"model_mix": {
"claude-sonnet-4": 51.1,
"gpt-4o": 42.5,
"gpt-4o-mini": 6.4
},
"percentile": 33.3,
"prior": 0,
"share_percent": 0.3,
"value": "user_7RkPq3Ne",
"z_score": -1.1
}
],
"by_model": [
{
"avg_cost_per_request": 352.1362,
"change_percent": 437.8,
"cost": 4577.77,
"prior": 851.13,
"prior_share_percent": 67.4,
"request_count": 13,
"share_percent": 49.9,
"value": "gpt-4o",
"z_score": 1.9
},
{
"avg_cost_per_request": 418.7971,
"change_percent": 610.6,
"cost": 2931.58,
"prior": 412.55,
"prior_share_percent": 32.6,
"request_count": 7,
"share_percent": 32,
"value": "claude-3-5-sonnet",
"z_score": 1
},
{
"avg_cost_per_request": 105.1989,
"change_percent": null,
"cost": 946.79,
"prior": 0,
"prior_share_percent": 0,
"request_count": 9,
"share_percent": 10.3,
"value": "gpt-4o-mini",
"z_score": -0.1
},
{
"avg_cost_per_request": 134.044,
"change_percent": null,
"cost": 670.22,
"prior": 0,
"prior_share_percent": 0,
"request_count": 5,
"share_percent": 7.3,
"value": "gemini-2.0-flash",
"z_score": -0.3
},
{
"avg_cost_per_request": 12.515,
"change_percent": null,
"cost": 25.03,
"prior": 0,
"prior_share_percent": 0,
"request_count": 2,
"share_percent": 0.3,
"value": "claude-sonnet-4",
"z_score": -0.8
}
],
"by_provider": [
{
"change_percent": 551,
"cost": 5540.56,
"prior": 851.13,
"prior_share_percent": 67.4,
"share_percent": 60.4,
"value": "openai",
"z_score": 1.2
},
{
"change_percent": 618.6,
"cost": 2964.61,
"prior": 412.55,
"prior_share_percent": 32.6,
"share_percent": 32.3,
"value": "anthropic",
"z_score": -0.1
},
{
"change_percent": null,
"cost": 670.22,
"prior": 0,
"prior_share_percent": 0,
"share_percent": 7.3,
"value": "google",
"z_score": -1.2
}
]
},
"totals": {
"active_end_users": {
"change_percent": null,
"current": 5,
"prior": 0
},
"cost": {
"change_percent": 626.1,
"current": 9175.39,
"prior": 1263.68
},
"margin": {
"change_points": 24.1,
"current": 24.1,
"prior": 0
},
"request_count": {
"change_percent": 2000,
"current": 42,
"prior": 2
},
"revenue": {
"change_percent": null,
"current": 12091.52,
"prior": 0
}
},
"unmapped_spend": {
"connect_billing_gap_cents": 3976,
"connect_billing_gap_percent": 0.4,
"instrumentation_gap_cents": 261399,
"instrumentation_gap_percent": 28.5
}
}
Error codes
Errors return the standard error envelope with a code, message, and a correlationId you can quote to support.
| Status | When it happens |
|---|---|
400 | Invalid request parameters. Check that start and end are valid ISO 8601 dates and that the requested range does not exceed 365 days. |
401 | Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY. |
403 | Forbidden. The API key is missing the costs:read or revenue:read scope; create or update a key with both scopes. |
429 | Rate limit or plan quota exceeded. Slow down and retry after the current window resets. |
503 | Service unavailable. The summary could not be computed due to a temporary database issue; retry the request. |
Rate limits and retries
Rate limit or plan quota exceeded. Slow down and retry after the current window resets.