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.

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 fields

Fields returned in the 200 response body. Nested objects are listed under their parent. A field marked optional may be absent from the body; one marked nullable is always present but its value may be null.

Field	Type	Description
`period`	`object`	Analysis period metadata.
`current`	`object`	Current analysis period.
`start`	`string`	ISO 8601 date string.
`end`	`string`	ISO 8601 date string.
`prior`	`object`	Prior comparison period. Auto-derived as the window of equal length immediately preceding start, or taken from prior_start and prior_end when both are provided.
`start`	`string`	ISO 8601 date string.
`end`	`string`	ISO 8601 date string.
`totals`	`object`	Period-over-period totals with change metrics.
`cost`	`object`	Total cost comparison. Values are USD dollars.
`current`	`number (double)`	Current period value.
`prior`	`number (double)`	Prior period value.
`change_percent`	`number (double)` nullable	Percent change from prior to current. Null when prior is 0 and current > 0 (new entry).
`revenue`	`object`	Total revenue comparison. Values are USD dollars.
`current`	`number (double)`	Current period value.
`prior`	`number (double)`	Prior period value.
`change_percent`	`number (double)` nullable	Percent change from prior to current. Null when prior is 0 and current > 0 (new entry).
`margin`	`object`	Overall margin comparison (percentage points).
`current`	`number (double)`	Current period margin percentage.
`prior`	`number (double)`	Prior period margin percentage.
`change_points`	`number (double)`	Percentage point change (current - prior).
`request_count`	`object`	Total request count comparison.
`current`	`number (double)`	Current period value.
`prior`	`number (double)`	Prior period value.
`change_percent`	`number (double)` nullable	Percent change from prior to current. Null when prior is 0 and current > 0 (new entry).
`active_end_users`	`object`	Active end user count comparison.
`current`	`number (double)`	Current period value.
`prior`	`number (double)`	Prior period value.
`change_percent`	`number (double)` nullable	Percent change from prior to current. Null when prior is 0 and current > 0 (new entry).
`distributions`	`object` nullable	Population distributions. Null when not requested via include parameter.
`cost_per_end_user`	`object` nullable	Cost distribution across end users, in USD dollars. Null when the period contains no qualifying data.
`mean`	`number (double)`	Arithmetic mean.
`median`	`number (double)`	Median (50th percentile).
`std_dev`	`number (double)`	Population standard deviation.
`p25`	`number (double)`	25th percentile.
`p75`	`number (double)`	75th percentile.
`p90`	`number (double)`	90th percentile.
`p99`	`number (double)`	99th percentile.
`skewness`	`number (double)` nullable	Fisher-Pearson skewness. Null if fewer than 3 users or zero variance.
`gini`	`number (double)` nullable	Gini coefficient (0 = perfect equality, 1 = maximum inequality). Null if fewer than 2 users.
`top_decile_share`	`number (double)` nullable	Percentage of total cost from the top 10% of users. Null if insufficient data.
`cost_per_request`	`object` nullable	Cost-per-request distribution across end users, in USD dollars. Null when the period contains no qualifying data.
`mean`	`number (double)`	Arithmetic mean.
`median`	`number (double)`	Median (50th percentile).
`std_dev`	`number (double)`	Population standard deviation.
`p25`	`number (double)`	25th percentile.
`p75`	`number (double)`	75th percentile.
`p90`	`number (double)`	90th percentile.
`p99`	`number (double)`	99th percentile.
`margin_per_end_user`	`object` nullable	Margin percentage distribution across end users. Null when the period contains no qualifying data.
`mean`	`number (double)`	Arithmetic mean.
`median`	`number (double)`	Median (50th percentile).
`std_dev`	`number (double)`	Population standard deviation.
`p25`	`number (double)`	25th percentile.
`p75`	`number (double)`	75th percentile.
`p90`	`number (double)`	90th percentile.
`p99`	`number (double)`	99th percentile.
`skewness`	`number (double)` nullable	Fisher-Pearson skewness. Null if fewer than 3 users or zero variance.
`below_zero_count`	`number (double)`	Number of end users with negative margin.
`daily_cost`	`object` nullable	Daily cost distribution with trend, in USD dollars. Null when the period contains no qualifying data.
`mean`	`number (double)`	Arithmetic mean of daily costs.
`median`	`number (double)`	Median daily cost.
`std_dev`	`number (double)`	Population standard deviation.
`min`	`number (double)`	Minimum daily cost.
`max`	`number (double)`	Maximum daily cost.
`cv`	`number (double)`	Coefficient of variation (std_dev / mean).
`trend`	`object` nullable	Linear regression trend. Null if fewer than 2 data points.
`r2`	`number (double)`
`direction`	`increasing` \| `decreasing` \| `stable`
`slope`	`number (double)`
`requests_per_end_user`	`object` nullable	Request count distribution across end users. Null when the period contains no qualifying data.
`mean`	`number (double)`	Arithmetic mean.
`median`	`number (double)`	Median (50th percentile).
`std_dev`	`number (double)`	Population standard deviation.
`p25`	`number (double)`	25th percentile.
`p75`	`number (double)`	75th percentile.
`p90`	`number (double)`	90th percentile.
`p99`	`number (double)`	99th percentile.
`top_movers`	`object`	Top movers by model, provider, end user, and custom dimensions.
`by_model`	`object[]`	Top movers by model.
`value`	`string`	Model slug.
`cost`	`number (double)`	Current period cost (USD dollars).
`prior`	`number (double)`	Prior period cost (USD dollars).
`change_percent`	`number (double)` nullable	Percent change. Null when prior is 0 and current > 0 (new entry).
`share_percent`	`number (double)`	Current period cost share (%).
`prior_share_percent`	`number (double)`	Prior period cost share (%).
`z_score`	`number (double)` nullable	Z-score of change relative to population. Null if all changes identical.
`request_count`	`number (double)`	Request count in current period.
`avg_cost_per_request`	`number (double)`	Average cost per request (USD dollars).
`by_provider`	`object[]`	Top movers by provider.
`value`	`string`	Provider slug.
`cost`	`number (double)`	Current period cost (USD dollars).
`prior`	`number (double)`	Prior period cost (USD dollars).
`change_percent`	`number (double)` nullable	Percent change. Null when prior is 0 and current > 0 (new entry).
`share_percent`	`number (double)`	Current period cost share (%).
`prior_share_percent`	`number (double)`	Prior period cost share (%).
`z_score`	`number (double)` nullable	Z-score of change relative to population. Null if all changes identical.
`by_end_user`	`object[]`	Top movers by end user.
`value`	`string`	End user external ID (the ID supplied on your usage events).
`cost`	`number (double)`	Current period cost (USD dollars).
`prior`	`number (double)`	Prior period cost (USD dollars).
`change_percent`	`number (double)` nullable	Percent change. Null when prior is 0 and current > 0 (new entry).
`share_percent`	`number (double)`	Current period cost share (%).
`z_score`	`number (double)` nullable	Z-score of change relative to population. Null if all changes identical.
`percentile`	`number (double)` nullable	Percentile rank by cost. Null if no data.
`margin`	`number (double)` nullable	Current period margin percentage. Null if no revenue data.
`margin_percentile`	`number (double)` nullable	Percentile rank by margin. Null if no margin data.
`model_mix`	`map of string to number (double)`	Model mix: model slug to cost share percentage.
`by_custom_dimension`	`map of string to object[]`	Top movers by custom dimension, keyed by dimension key.
`value`	`string`	Dimension value.
`cost`	`number (double)`	Current period cost (USD dollars).
`prior`	`number (double)`	Prior period cost (USD dollars).
`change_percent`	`number (double)` nullable	Percent change. Null when prior is 0 and current > 0 (new entry).
`share_percent`	`number (double)`	Current period cost share (%).
`z_score`	`number (double)` nullable	Z-score of change relative to population. Null if all changes identical.
`end_user_count`	`number (double)`	Number of distinct end users.
`request_count`	`number (double)`	Total request count.
`margin_outliers`	`object[]`	End users whose margin z-score is below -1.5. Empty when no outliers are found, when fewer than 2 end users have margin data, or when all margins are identical (zero variance).
`end_user`	`string`	End user external ID (the ID supplied on your usage events).
`margin`	`number (double)`	Margin percentage.
`deviation_from_mean`	`number (double)`	Deviation from population mean (percentage points).
`z_score`	`number (double)` nullable	Z-score (how many std devs below mean). Null if zero variance.
`cost`	`number (double)`	Total cost for this end user (USD dollars).
`model_mix`	`map of string to number (double)`	Model mix: model slug to cost share percentage.
`correlations`	`object`	Cross-metric Pearson correlations.
`cost_vs_request_volume`	`number (double)` nullable	Pearson correlation between cost and request volume per end user. Null if insufficient data.
`margin_vs_model_mix`	`number (double)` nullable	Pearson correlation between margin and model mix concentration (HHI). Null if insufficient data.
`unmapped_spend`	`object`	Aggregated unmapped-spend breakdown.
`instrumentation_gap_cents`	`number (double)`	Spend recorded without an end user ID, in integer USD cents. Close this gap by passing an end user ID in your usage events.
`instrumentation_gap_percent`	`number (double)`	instrumentation_gap_cents as a percent of total spend. A real 0, not null, when there is no spend.
`connect_billing_gap_cents`	`number (double)`	Spend for end users with no connected Stripe revenue data, in integer USD cents. Close this gap by connecting Stripe.
`connect_billing_gap_percent`	`number (double)`	connect_billing_gap_cents as a percent of total spend. A real 0, not null, when there is no spend.

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; OR the current plan does not include the summary-ai capability.
`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.

GEThttps://api.bearlumen.com/v1/insights/summary

Response example

Success response (200):

{
  "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
  }
}