End User Costs API
Get cost trend for a specific end-user
Returns time-series cost data with adaptive granularity for the specified end-user. Call it with a GET request to /end-user-costs/{externalId}/trend, authenticated with a restricted API key and the "costs:read" scope.
Returns time-series cost data with adaptive granularity for the specified end-user. Granularity is selected from the date range: 30 days or less returns daily points, 31-90 days weekly, longer ranges monthly. The response granularity field reports which was used. Periods with no events are omitted from dataPoints (not returned as zero-cost points); fill gaps client-side if your chart requires a continuous series. 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 scope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
externalId | path | string | Yes | End-user identifier you assigned when sending usage events (the user_id field on POST /usage-events). An end user exists only after at least one event referencing this identifier has been ingested; unknown identifiers return 404. |
start_date | query | string | Yes | Start of date range (ISO 8601, inclusive). |
end_date | query | string | Yes | End of date range (ISO 8601, exclusive). |
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 |
|---|---|---|
end_user_id | string | Bear Lumen internal end-user ID (UUID). Use the externalId path parameter for lookups, not this value. |
series | object[] | Time-series data. |
key | string | Series key (the end-user external ID you queried). |
label | string | Series label (currently the end-user external ID). |
data_points | object[] | Data points. Periods with no events are omitted (not returned as zero-cost points); fill gaps client-side if your chart requires a continuous series. |
date | string | Period date (ISO 8601). |
cost | string | Total cost for this period (decimal string). |
event_count | number (double) | Number of events. |
granularity | daily | weekly | monthly | Granularity used for the series, selected from the date range: 30 days or less returns daily, 31-90 days weekly, longer ranges monthly. |
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 data. Check that required query parameters are present and that start_date and end_date are valid ISO 8601 dates. |
401 | Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY. |
403 | API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry. |
404 | End user not found. The identifier must match the user_id value sent on at least one ingested usage event. |
429 | Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset). |
Rate limits and retries
Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).